guided tour suggestions

guided tour suggestions

[Karl Berry]

We received this report on webmasters (thanks Daniel) ...


From: daniel@brockman.se

I am reading the newly-installed Emacs guided tour[1] and
taking notes as I go along.

First, this seems wrong (it's the other way around):

    C-v  Previous screen        M-v  Next screen

Second, this seems like an overstatement (Perl has quite a
lot of regexp constructs):

    Emacs regexps support a superset of Perl's regexp constructs.

As just one example, Emacs doesn't support negative lookahead.

Third, here,

    M-x calc    An RPN calculator.

maybe it is better to mention `M-x calculator' instead?

Fourth, here,

    C-x (          Start recording macro
    C-x )          Stop recording macro
    C-x e          Play back macro once
    C-x e e e...   Play back macro multiple times

maybe add this item:

    M-0 C-x e      Play back macro over and over until it fails

Fifth, this

    M-x shell      New shell buffer
    C-u M-x shell  New shell buffer with specified name

should probably look like this:

    M-x shell      Switch to shell buffer
    C-u M-x shell  Make new shell buffer

Sixth, this also seems like an overstatement:

   Emacs ships with a major mode for pretty much every
   widely used programming language (and then some).

Perhaps say it like this instead:

   Emacs ships with major modes for many widely used
   programming languages, markup languages, configuration
   file formats, etc.  In almost all cases, major modes for
   unsupported formats are available as extension packages.
   (Take a look at <a href="http://www.emacswiki.org/">EmacsWiki</a>.)

-- 
Daniel Brockman <daniel@brockman.se>

[1]  http://www.gnu.org/software/emacs/tour/

Re: guided tour suggestions

[Phil Sung]

karl@freefriends.org (Karl Berry) writes:
> From: daniel@brockman.se
>
> I am reading the newly-installed Emacs guided tour[1] and
> taking notes as I go along.

Thanks for your fixes! I've incorporated your suggestions (patch below).

Could a webmaster please install this patch? Thank you.

--Phil

----

Index: tour/index.html
===================================================================
RCS file: /web/emacs/emacs/tour/index.html,v
retrieving revision 1.6
diff -c -c -r1.6 index.html
*** tour/index.html	2 May 2007 11:17:56 -0000	1.6
--- tour/index.html	3 May 2007 20:04:25 -0000
***************
*** 155,161 ****
    <tr><td><tt>C-a</tt></td><td>Beginning of line</td>      <td><tt>C-e</tt></td><td>End of line</td></tr>
    <tr><td><tt>M-f</tt></td><td>Forward one word</td>       <td><tt>M-b</tt></td><td>Back one word</td></tr>
    <tr><td><tt>M-a</tt></td><td>Previous sentence</td>      <td><tt>M-e</tt></td><td>Next sentence</td></tr>
!   <tr><td><tt>C-v</tt></td><td>Previous screen</td>        <td><tt>M-v</tt></td><td>Next screen</td></tr>
    <tr><td><tt>M-&lt;</tt></td><td>Beginning of buffer</td> <td><tt>M-&gt;</tt></td><td>End of buffer</td></tr>
  </table>
  
--- 155,161 ----
    <tr><td><tt>C-a</tt></td><td>Beginning of line</td>      <td><tt>C-e</tt></td><td>End of line</td></tr>
    <tr><td><tt>M-f</tt></td><td>Forward one word</td>       <td><tt>M-b</tt></td><td>Back one word</td></tr>
    <tr><td><tt>M-a</tt></td><td>Previous sentence</td>      <td><tt>M-e</tt></td><td>Next sentence</td></tr>
!   <tr><td><tt>M-v</tt></td><td>Previous screen</td>        <td><tt>C-v</tt></td><td>Next screen</td></tr>
    <tr><td><tt>M-&lt;</tt></td><td>Beginning of buffer</td> <td><tt>M-&gt;</tt></td><td>End of buffer</td></tr>
  </table>
  
***************
*** 506,513 ****
  <p>See <tt>(info "(emacs)Regexps")</tt> for more information about regexp
    syntax.</p>
  
- <p>Emacs regexps support a superset of Perl's regexp constructs. </p>
- 
  <p>If you're new to regexps, or you are constructing a particularly complicated
    regexp, you can use the regexp builder (<tt>M-x re-builder</tt>). This
    command pops up a separate window in which you can test out your regexp, and
--- 506,511 ----
***************
*** 599,605 ****
  <p>Here are some more assorted tools:</p>
  
  <table>
!   <tr><td><tt>M-x calc</tt></td><td>An RPN calculator.</td></tr>
    <tr><td><tt>M-x calendar</tt></td><td>A calendar.</td></tr>
    <tr><td><tt>M-x phases-of-moon</tt></td><td>Shows upcoming quarters of the
        moon.</td></tr>
--- 597,603 ----
  <p>Here are some more assorted tools:</p>
  
  <table>
!   <tr><td><tt>M-x calculator</tt></td><td>A calculator.</td></tr>
    <tr><td><tt>M-x calendar</tt></td><td>A calendar.</td></tr>
    <tr><td><tt>M-x phases-of-moon</tt></td><td>Shows upcoming quarters of the
        moon.</td></tr>
***************
*** 712,717 ****
--- 710,716 ----
    <tr><td><tt>C-x )</tt></td><td>Stop recording macro</td></tr>
    <tr><td><tt>C-x e</tt></td><td>Play back macro once</td></tr>
    <tr><td><tt>C-x e e e</tt>...</td><td>Play back macro multiple times</td></tr>
+   <tr><td><tt>M-0 C-x e</tt></td><td>Play back macro over and over until it fails</td></tr>
  </table>
  
  <p>For example, this sequence of keys does the exact same transformation that
***************
*** 785,791 ****
  <table>
    <tr><td><tt>C-/</tt></td><td>Undo</td></tr>
    <tr><td><tt>C-u C-/</tt></td><td>Undo within current region</td></tr>
!   <tr><td><tt>M-x shell</tt></td><td>New shell buffer</td></tr>
    <tr><td><tt>C-u M-x shell</tt></td><td>New shell buffer with specified
        name</td></tr>
  </table>
--- 784,790 ----
  <table>
    <tr><td><tt>C-/</tt></td><td>Undo</td></tr>
    <tr><td><tt>C-u C-/</tt></td><td>Undo within current region</td></tr>
!   <tr><td><tt>M-x shell</tt></td><td>Switch to shell buffer</td></tr>
    <tr><td><tt>C-u M-x shell</tt></td><td>New shell buffer with specified
        name</td></tr>
  </table>
***************
*** 828,841 ****
    use a separate command which will create a buffer and initialize it for you:</p>
  
  <table>
!   <tr><td><tt>M-x shell</tt></td><td>Create a new shell buffer</td></tr>
    <tr><td><tt>M-x dired</tt></td><td>Create a new Dired buffer</td></tr>
  </table>
  
! <p>Emacs ships with a major mode for pretty much every widely used programming
!   language (and then some). These major modes provide language-specific
!   indentation rules and syntax highlighting, and other language-specific
!   commands. For starters:</p>
  
  <table class="greytop">
    <thead>
--- 827,841 ----
    use a separate command which will create a buffer and initialize it for you:</p>
  
  <table>
!   <tr><td><tt>M-x shell</tt></td><td>Create a new shell buffer (or switch to an
!       existing one)</td></tr>
    <tr><td><tt>M-x dired</tt></td><td>Create a new Dired buffer</td></tr>
  </table>
  
! <p>Emacs ships with major modes for many widely used programming languages,
!   markup languages, and configuration file formats. These major modes provide
!   language-specific indentation rules and syntax highlighting, and other
!   language-specific commands. Some examples:</p>
  
  <table class="greytop">
    <thead>
***************
*** 846,851 ****
--- 846,855 ----
    <tr><td>HTML</td><td>Insert and close tags; preview in browser</td></tr>
  </table>
  
+ <p>In almost all cases, major modes for unsupported formats are available as
+   extension packages. You can find many of them
+   on <a href="http://www.emacswiki.org/">EmacsWiki</a>.</p>
+ 
  <p>See <tt>(info "(emacs)Major Modes")</tt> for more information.</p>
  
  <h3>Minor modes</h3>

Re: guided tour suggestions

[Chong Yidong]

I've just managed to find the time to read through the guided tour.  I
must say, it's a very impressive job.  I have a few suggestions to
make:

0. Am I the only one that thinks the parts of the text in <tt> are too
   small to be legible?  Or are my Firefox fonts screwed up?

1. The screenshots on http://www.gnu.org/software/emacs/tour/ are too
   zoomed out to be legible.  I guess the reason for this is so that
   the entire Emacs window can be displayed.  I think it would be
   better if the screenshot images on the main page of the tour are at
   100% zoom, and cropped so that only the relevant part of the window
   is seen.  When you click on each image, it should bring you to a
   bigger imager showing the entire Emacs window.

2. In the Mark section, under the column labelled "When you...", the
   first entry is "C-SPC".  To be grammatical, this should be "type
   C-SPC".  In the same column, the entry "Exit a search (C-s or C-r)"
   is confusing: these are the keystrokes to enter a search, not exit
   a search.

3. In the section on Isearch, the sentioned "You can incremental
   search backwards" is grammatically fishy.  Maybe "You can perform a
   backward incremental search" is better.

4. In "Integration with common tools", I think we should recommend
   M-x man instead of M-x woman.  As far as I know, the latter is only
   useful on systems where man is unavailable (though that may just be
   sexism).

5. In the section on Macros, I think we should recommend the F3 and F4
   keys new to Emacs 22, since they are easier to use than the old
   kmacro keys.

6. In the Emacs Help Facilities section, the suggestion to run Info
   with M-x info can probably use C-h i instead.  Also, the sentence
   "You can also read the GNU Emacs manual in Emacs with (info
   "(emacs)")" is confusing -- do you mean the menu-bar?

Also, I wonder if the tour should mention transient mark mode.  Now
that font-lock-mode is on by default, transient mark mode is IMHO the
reigning champion for Feature That Should Be Turned On By Default But
Isn't.

Re: guided tour suggestions

[David Kastrup]

Chong Yidong <cyd@mit.edu> writes:

> Also, I wonder if the tour should mention transient mark mode.  Now
> that font-lock-mode is on by default, transient mark mode is IMHO
> the reigning champion for Feature That Should Be Turned On By
> Default But Isn't.

I disagree strongly.  Temporary transient mark mode is quite filling
that niche.  The constant interference of unintended active regions
with both buffer display and operation is not making permanent
transient-mark-mode something I would want enabled.

-- 
David Kastrup

RE: guided tour suggestions

[Drew Adams]

> 0. Am I the only one that thinks the parts of the text in <tt> are too
>    small to be legible?  Or are my Firefox fonts screwed up?

They look OK for me, in IE6.0.

> 1. The screenshots on http://www.gnu.org/software/emacs/tour/ are too
>    zoomed out to be legible.  I guess the reason for this is so that
>    the entire Emacs window can be displayed.  I think it would be
>    better if the screenshot images on the main page of the tour are at
>    100% zoom, and cropped so that only the relevant part of the window
>    is seen.  When you click on each image, it should bring you to a
>    bigger imager showing the entire Emacs window.

Generally agree. However, showing full-size screenshots takes a lot more
screen space and so interrupts the reading flow. Show at least some of the
screenshots (e.g. ediff, mail) reduced and uncropped, when it is important
to give an idea of the entire layout (but still let you click to get
full-size).

* No need for a screenshot to show the grocery list; just print the list.

* The code screenshot should show a language that Emacs newbies might be
familiar with, instead of Emacs Lisp - e.g. C++, Java.

* There could be a *grep* or *compilation* screenshot, perhaps showing
another window with found source code.

* There could be a screenshot showing incremental search. It should be
repeated in the search section.

* The ediff screenshot is very good, but the tiny Ediff frame should be
moved from in front of the other frame, so you can tell it is a frame.

* The dired screenshot could be better, perhaps showing code files in a
project, with an inserted subdir, some marked files, and an interaction in
the minibuffer.

* There could be a screenshot showing Help or Info in use.

* The shell screenshot could lose the quotation - it's confusing here.

* The email screenshot could be better chosen, perhaps.

* I would lose the tetris screenshot. If the point is to show that Emacs has
play activities too, I'd skip this shot. Compared to play things available
elsewhere, this is not very convincing. Better to show a good conversation
with the shrink. I'd skip this stuff altogether, personally.

* Put the hexl screenshot last, if at all.

> 5. In the section on Macros, I think we should recommend the F3 and F4
>    keys new to Emacs 22, since they are easier to use than the old
>    kmacro keys.

No real opinion on that, except that some keyboards don't have function
keys, and some people never leave the home keys. I don't know if there is a
general policy on this.

The section should be called "Keyboard Macros" (or "Recording Interactions"
or some such), however, not Macros.

> Also, I wonder if the tour should mention transient mark mode.  Now
> that font-lock-mode is on by default, transient mark mode is IMHO the
> reigning champion for Feature That Should Be Turned On By Default But
> Isn't.

I agree. In fact, I vote for turning on delete-selection-mode by default.

However, since it's not on by default, I don't think the tour should mention
it. If it were on, I'd prefer that we present the region in the tour in
d-s-m terms (simple) - helas. Delete selection mode is closer to what most
newbies will be familiar with (besides being better for everyone ;-)).

BTW, wrt "the constant interference of unintended active regions with both
buffer display and operation" (David), I've never found it to interfere with
anything I do in Emacs. Anyway, we don't want to open that hornet's nest
this time around. Just chalk me up as one more vote in favor of d-s-m, but
not in favor of mentioning it in the tour, because you have to turn it on.

I haven't had a chance to read the tour yet (!); I just took a quick look at
the sections Chong referred to and skimmed some more. Looks generally good
so far.

The order seems a bit weird: It seems odd to tour tramp, server, and
registers before "Common Emacs concepts" such as prefix args, modes, and
minibuffer, for instance. I would say users should tour "Learning about
Emacs" near the beginning (and not call it Learning _more_ about Emacs) -
teaching how to learn is one of the first things to get across, not the
last.

I'm not sure what I think about the presentation of Undo. It is generally
clear, but it looks a bit intimidating because of the diagrams. If we keep
the diagrams, perhaps add a diagram showing Emacs undo that corresponds to
the first two diagrams. We don't see Emacs undo until the discussion of
accessing the past after performing a non-undo/redo action. That is, we only
see an Emacs undo chain that corresponds to the 3rd diagram.

I know that some people have found Emacs's undo disconcerting, but I've
never found it anything but intuitive, from the beginning. Cell diagrams
seem complicated for presenting this, to me. I feel ambivalent about the
diagrams, actually. If you trace them through carefully, I suppose they can
help, but I think it's a lot easier to get a mental model of Emacs undo by
just trying it.

It might be useful to state that, unlike other editors, you can, in effect,
undo past undo actions (without going into detail trying to describe exactly
what that means).

"Useful features" is a catch-all category. It's content needs to be moved
(restructure). For example, move keyboard macros to the editing section.

What feature is not useful? "Useful features" even includes
phases-of-the-moon, which is hardly an example of "Integration with common
tools". No need to mention such stuff, IMO; users will appreciate it more
when they find it, as an "extra" (a la easter egg).

The region is not presented as such in a dedicated section (the closest
thing is the Mark section) - it is mentioned here and there. Narrowing
should be presented with the region.

We might want to mention the mouse in connection with the region, as Emacs'
mouse is enhanced wrt what people are used to elsewhere. Might, might not.

We might mention more about Emacs's features for editing code. Things such
as indentation that we take for granted, for instance.

HTH. Thanks for this tour; it should help new users.

Re: guided tour suggestions

[Mathias Dahl]

> > 0. Am I the only one that thinks the parts of the text in <tt> are too
> >    small to be legible?  Or are my Firefox fonts screwed up?
>
> They look OK for me, in IE6.0.

That font is very small for me too, running FF 2 under Mandriva GNU/Linux.

> * The code screenshot should show a language that Emacs newbies might be
> familiar with, instead of Emacs Lisp - e.g. C++, Java.

Agree.

> The section should be called "Keyboard Macros" (or "Recording Interactions"
> or some such), however, not Macros.

Agree.

> It might be useful to state that, unlike other editors, you can, in effect,
> undo past undo actions (without going into detail trying to describe exactly
> what that means).

I agree, this could be enough.

> What feature is not useful? "Useful features" even includes
> phases-of-the-moon

Indeed it does. In my work I work with collegues in Sri Lanka, where
they celebrate "Poya" around full moons, so it is very useful. :)

Thanks for this tour!

Re: guided tour suggestions

[David House]

On 02/06/07, Drew Adams <drew.adams@oracle.com> wrote:
> * There could be a *grep* or *compilation* screenshot, perhaps showing
> another window with found source code.

We could do the traditional IDE screenshot with grep, compilation,
speedbar and so on buffers open.

> * There could be a screenshot showing incremental search. It should be
> repeated in the search section.

I agree. Incremental search is both one of Emacs's most useful and
most GUI-heavy features, I'd love to see screenshots for both
incremental search and query-replace.

> * I would lose the tetris screenshot. If the point is to show that Emacs has
> play activities too, I'd skip this shot. Compared to play things available
> elsewhere, this is not very convincing. Better to show a good conversation
> with the shrink. I'd skip this stuff altogether, personally.

Keeping a screenshot for something like tetris, blackbox or doctor
would be nice in terms of keeping a more lightweight feel to the
article. They also give the impression that Emacs really does have
everything. I vote for keeping them.

> * Put the hexl screenshot last, if at all.

Agreed. Who uses hexl more than, say, dired?

> I agree. In fact, I vote for turning on delete-selection-mode by default.

Yes, me too.

> I'm not sure what I think about the presentation of Undo. It is generally
> clear, but it looks a bit intimidating because of the diagrams. If we keep
> the diagrams, perhaps add a diagram showing Emacs undo that corresponds to
> the first two diagrams. We don't see Emacs undo until the discussion of
> accessing the past after performing a non-undo/redo action. That is, we only
> see an Emacs undo chain that corresponds to the 3rd diagram.

I really found these diagrams helpful. Emacs does have a rather funky
undo policy with respect to the rest of the editors on this planet,
and it's worth explaining to avoid confusion. It's also a nice example
of how Emacs does things differently to be more powerful.

> What feature is not useful? "Useful features" even includes
> phases-of-the-moon, which is hardly an example of "Integration with common
> tools". No need to mention such stuff, IMO; users will appreciate it more
> when they find it, as an "extra" (a la easter egg).

Again, I'd like to keep this in, for the sake of humour and to give
the impression that Emacs has everything you'd ever want, and then
some.

> We might mention more about Emacs's features for editing code. Things such
> as indentation that we take for granted, for instance.

Agreed. Emacs should be pushed primarily as a coding platform.

-- 
-David House, dmhouse@gmail.com

Re: guided tour suggestions

[Phil Sung]

Sorry for the delay, I just got back from traveling.

Thanks, all, for your suggestions. I've incorporated some of them and am
thinking about how to implement the rest. I had been sitting on another draft
which improves the sometimes awkward wording of the original version, and
removes a little bit of material which is probably not of interest to
beginners, so I've posted that.

The in-progress version is here:
http://stuff.mit.edu/iap/emacs/emacs-guided-tour-1.html

Chong Yidong <cyd@MIT.EDU> writes:
> parts of the text in <tt> are too small to be legible
Indeed, they are. Sorry about that. (I think it's something about the GNU
stylesheet which I didn't notice before.)

> In the Mark section, under the column labelled "When you...", the first entry
> is "C-SPC". To be grammatical, this should be "type C-SPC". In the same
> column, the entry "Exit a search (C-s or C-r)" is confusing...
Fixed.

> In the section on Isearch, the sentioned "You can incremental search
> backwards" is grammatically fishy. Maybe "You can perform a backward
> incremental search" is better.
Changed.

> In "Integration with common tools", I think we should recommend M-x man
> instead of M-x woman.
Changed. My basis for recommending M-x woman was that it was more colorful...
;-)

> In the Emacs Help Facilities section, the suggestion to run Info with M-x
> info can probably use C-h i instead.
Ah, of course. Actually, I should have just suggested C-h r (info-emacs-manual)
here.

By the way, what is the preferred way to direct the reader to a specific Info
node? Should I suggest (info "(emacs)NODE") (as I have been doing) or something
like C-h r g NODE RET?

> Also, I wonder if the tour should mention transient mark mode. Now that
> font-lock-mode is on by default, transient mark mode is IMHO the reigning
> champion for Feature That Should Be Turned On By Default But Isn't.
I've added a paragraph for transient-mark-mode.

Drew Adams <drew.adams@oracle.com> writes:
>> 1. The screenshots on http://www.gnu.org/software/emacs/tour/ are too
>>    zoomed out to be legible.  I guess the reason for this is so that
>>    the entire Emacs window can be displayed.  I think it would be
>>    better if the screenshot images on the main page of the tour are at
>>    100% zoom, and cropped so that only the relevant part of the window
>>    is seen.  When you click on each image, it should bring you to a
>>    bigger imager showing the entire Emacs window.
>
> Generally agree. However, showing full-size screenshots takes a lot more
> screen space and so interrupts the reading flow. Show at least some of the
> screenshots (e.g. ediff, mail) reduced and uncropped, when it is important
> to give an idea of the entire layout (but still let you click to get
> full-size).
>
> * [screenshot ideas]

I've added and improved some screenshots. Most are cropped to show some
interesting part of the frame.

* The first part has improved screenshots for a C buffer, EDiff, and Dired, and
  a new one for GDB. I'll redo Gnus and shell shortly.
* I've added screenshots, in their respective sections, for isearch, compile,
  GDB, grep, function documentation, and the manual.

>> 5. In the section on Macros, I think we should recommend the F3 and F4
>>    keys new to Emacs 22, since they are easier to use than the old
>>    kmacro keys.
Done.

> No real opinion on that, except that some keyboards don't have function
> keys, and some people never leave the home keys.
I suppose. But the fact that the manual recommends F3 and F4 justifies this
change.

> The section should be called "Keyboard Macros" (or "Recording Interactions"
> or some such), however, not Macros.
Changed.

> The order seems a bit weird: It seems odd to tour tramp, server, and
> registers before "Common Emacs concepts" such as prefix args, modes, and
> minibuffer, for instance.

> "Useful features" is a catch-all category. It's content needs to be moved
> (restructure). For example, move keyboard macros to the editing section.

> I would say users should tour "Learning about Emacs" near the beginning (and
> not call it Learning _more_ about Emacs) - teaching how to learn is one of
> the first things to get across, not the last.

Indeed, the ordering is sort of weird. This material is adapted from a lecture,
so suggestions for a more sensible organization are welcome.

The thing is, I wanted to convey "why Emacs is useful" with only a secondary
goal of conveying "how to use Emacs"-- after all, this tour is not, and does
not try to be, the Manual or the Tutorial. But modulo that I will try to
mention the help features earlier and put things in a better order.

> It might be useful to state that, unlike other editors, you can, in effect,
> undo past undo actions (without going into detail trying to describe exactly
> what that means).
I agree that the undo pictures are somewhat intimidating in this context, so
I've removed them. (Sorry, David.)

> The region is not presented as such in a dedicated section (the closest
> thing is the Mark section) - it is mentioned here and there. Narrowing
> should be presented with the region.
I've added a section for the region. Narrowing and transient-mark-mode are in
it.

> We might mention more about Emacs's features for editing code. Things such
> as indentation that we take for granted, for instance.
Good point. I'll think about adding more material in this vein.

David House <dmhouse@gmail.com> writes:
> Again, I'd like to keep [phases-of-moon], for the sake of humour and to give
> the impression that Emacs has everything you'd ever want, and then some.
This captures my sentiment about the tour. I hope that it will get readers to
think "Well, if Emacs has Tetris, then maybe it has _____ too" and then to
actually look for features in the docs or on the web.


Regards,
Phil

RE: guided tour suggestions

[Drew Adams]

> The in-progress version is here:
> http://stuff.mit.edu/iap/emacs/emacs-guided-tour-1.html

Much better! Thanks.

I suspect that others will disagree, but I'd suggest mentioning something
about the mouse in the Region section. I'd also suggest dropping mention of
M-@ and M-h (C-x h is important, however, and we should mention that this is
essentially "Select All" (often C-a)).

Similarly, I wouldn't bother with all of the kill flavors: kill N lines,
unless this is to be used as an illustration of C-u (in which case it
doesn't belong in the Killing text section). I wouldn't mention M-k or M-z.
I wouldn't mention so many key bindings, in general. I wouldn't mention
anything about movement or selection of sentences and paragraphs.

I agree 100%, BTW, that the aim here is not to teach how to use Emacs but to
show a little of what's available. That's why key bindings are not so
important to describe. (In fact, we could even just stick to menu items.) If
this were more about teaching use, then I'd say we need to mention C-x C-s
and C-x C-w (and...).

Re: guided tour suggestions

[Phil Sung]

Drew Adams <drew.adams@oracle.com> writes:
> I'd suggest mentioning something about the mouse in the Region section.

Ok. Is there something remarkable about mouse usage other than click-and-drag
to select a region? (I don't really use the mouse in Emacs.)

> I agree 100%, BTW, that the aim here is not to teach how to use Emacs but to
> show a little of what's available. That's why key bindings are not so
> important to describe.

Good point. I will trim some key binding mentions.


Previous suggestions which were made:

* Mention help features earlier

  I now mention the manual close to the beginning, and function documentation
  right after the section on editing commands.

* Emphasize Emacs as a coding environment

  There are now screenshots of GDB, compile, grep, and shell, and further
  information about what programming major modes can do.

Again, the draft is at:
<http://stuff.mit.edu/iap/emacs/emacs-guided-tour-1.html>

If no one objects, I will ask the webmasters to replace the version on gnu.org
with this soon.

--Phil

RE: guided tour suggestions

[Drew Adams]

> > I'd suggest mentioning something about the mouse in the Region section.
>
> Ok. Is there something remarkable about mouse usage other than
> click-and-drag
> to select a region? (I don't really use the mouse in Emacs.)

Yes, double- and triple-click to select nested things, depending on context.
Left, then right click to select, plus right click again to extend/reduce. I
imagine that this is documented in the manual - it should be. Also, but
probably not worth mentioning because it is often better in other apps, some
buffers offer contextual mouse menus (sometimes modifier+mouse-1, sometimes
mouse-3).

The rest sounds good. Thanks for working on this; it will be helpful to
everyone.

Re: guided tour suggestions

[David Kastrup]

Phil Sung <psung@MIT.EDU> writes:

> Previous suggestions which were made:
>
> * Mention help features earlier
>
>   I now mention the manual close to the beginning, and function documentation
>   right after the section on editing commands.
>
> * Emphasize Emacs as a coding environment
>
>   There are now screenshots of GDB, compile, grep, and shell, and further
>   information about what programming major modes can do.
>
> Again, the draft is at:
> <http://stuff.mit.edu/iap/emacs/emacs-guided-tour-1.html>
>
> If no one objects, I will ask the webmasters to replace the version
> on gnu.org with this soon.

I just took a look at it: Ugh!  This is supposed to _advertise_ Emacs,
and I have enough of a fight convincing people that Emacs has made the
step into the twenty-first century.  The guided tour is completely
unsuitable for that.  It shows an Emacs a) compiled without a modern
toolkit (Gtk+, Windows or Mac) b) without menus c) without toolbars d)
without scrollbars (for heaven's sake!)  e) without font diversity.
The only thing hinting at fonts is a man-page (not info or even
woman-page!)  with some bold headings, and then those headings have
the identical crowded monospace size as the rest.  f) without file
dialogs g) without tooltips h) without any non-ASCII character

The only exception to this theme is a screenshot of a Tetris game,
quite irrelevant.

Would it be possible to make the screenshots with emacs -Q so that
people see what they get out of the box instead of after an
Emacs-18-tty-happy user has finished refurbishing Emacs 22 to a
Zen-like emptiness?

It is, after all, Emacs 22 we are trying to sell to the unwashed
masses.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: guided tour suggestions

[Nick Roberts]

 > > Again, the draft is at:
 > > <http://stuff.mit.edu/iap/emacs/emacs-guided-tour-1.html>
 > >
 > > If no one objects, I will ask the webmasters to replace the version
 > > on gnu.org with this soon.
 > 
 > I just took a look at it: Ugh!  This is supposed to _advertise_ Emacs,
 > and I have enough of a fight convincing people that Emacs has made the
 > step into the twenty-first century.  The guided tour is completely
 > unsuitable for that...

There have been many opportunities to comment on the guided tour before.
Some of your comments might be legitimate but unfortunately, as usual, your
manner is highly antagonistic and counterproductive to the fragile spirit
of co-operation.


-- 
Nick                                           http://www.inet.net.nz/~nickrob

Re: guided tour suggestions

[David Kastrup]

Nick Roberts <nickrob@snap.net.nz> writes:

>  > > Again, the draft is at:
>  > > <http://stuff.mit.edu/iap/emacs/emacs-guided-tour-1.html>
>  > >
>  > > If no one objects, I will ask the webmasters to replace the version
>  > > on gnu.org with this soon.
>  > 
>  > I just took a look at it: Ugh!  This is supposed to _advertise_ Emacs,
>  > and I have enough of a fight convincing people that Emacs has made the
>  > step into the twenty-first century.  The guided tour is completely
>  > unsuitable for that...
>
> There have been many opportunities to comment on the guided tour
> before.

I have confused the discussion about it with a slide show in PDF
format (a different project also discussed here, which I glanced at).

So I did not actually see the guided tour in the context of this
discussion, but only when I got into some fight in comp.emacs where
somebody steadfastly (from decade-old short exposure, it would seem)
claimed that Emacs was a tty application without any useful help or
GUI features.

So I looked for screenshots from off the main page of Emacs.  Apart
from the guided tour (which actually rather proved than disproved the
original poster's point), I came up with a blank.  I had to refer to
the screenshots of AUCTeX instead.

Now this complete absence of any useful screenshots or demo material
(the main Emacs page <URL:http://www.gnu.org/software/emacs/> contains
not a single screenshot but refers to the tour at the top) is not the
fault of the tour: it is filling a complete void here.

Nevertheless, I consider it a mistake to have made the screenshots
with what appears like emacs --barebones (or what it was called).

> Some of your comments might be legitimate but unfortunately, as
> usual, your manner is highly antagonistic and counterproductive to
> the fragile spirit of co-operation.

Whatever.  In the current form, I feel myself unable to refer people
to the guided tour as an exposition to Emacs _unless_ they have
already installed Emacs and are planning on using the tour as a
_tutorial_.  But as an exposition, a tour which restricts its
demonstration of human/Emacs interaction to emacs -nw (and even emacs
-nw would offer menus) is not encouraging.

Even if one does not want to work on the basics of the tour itself,
the screenshots (which are the only ones reachable from the main Emacs
page) should rather reflect what a new user will be working with,
namely emacs -Q.

After all, we have fought manmonths of time over the best options and
look to present to beginners by default.  Why not show the result of
all that work?

-- 
David Kastrup

Re: guided tour suggestions

[Phil Sung]

David Kastrup <dak@gnu.org> writes:
> Would it be possible to make the screenshots with emacs -Q so that people see
> what they get out of the box ... ?

Good idea.

> The guided tour ... shows an Emacs a) compiled without a modern toolkit
> (Gtk+, Windows or Mac) b) without menus c) without toolbars d) without
> scrollbars (for heaven's sake!) e) without font diversity. The only thing
> hinting at fonts is a man-page f) without file dialogs g) without tooltips h)
> without any non-ASCII character

When I get a chance, I will make some screenshots with the default UI setup,
and with more complex formatting/characters.

--Phil

Re: guided tour suggestions

[David Kastrup]

Phil Sung <psung@MIT.EDU> writes:

> David Kastrup <dak@gnu.org> writes:
>> Would it be possible to make the screenshots with emacs -Q so that people see
>> what they get out of the box ... ?
>
> Good idea.
>
>> The guided tour ... shows an Emacs a) compiled without a modern
>> toolkit (Gtk+, Windows or Mac) b) without menus c) without toolbars
>> d) without scrollbars (for heaven's sake!) e) without font
>> diversity. The only thing hinting at fonts is a man-page f) without
>> file dialogs g) without tooltips h) without any non-ASCII character
>
> When I get a chance, I will make some screenshots with the default
> UI setup, and with more complex formatting/characters.

Very much appreciated.  One of the problems with promoting Emacs
nowadays are users who tried it 10 years ago and were not getting
along with it.  Dispelling their (and their audience's) preconceptions
is easier with more graphical material.

I am aware that one of the most frequent customizations is turning off
the toolbar in order to maximize screen estate and minimize clutter.
For a live showoff of the skills of an experienced user, this might be
somewhat feasible.  But as soon as we are getting into (live or
off-line) tutorial reign, it becomes a much better idea to show off
and use the menus: that way, people have a chance of _following_ what
you are doing, and maybe even of doing it by themselves.  And they
have the cues for trying it by themselves and remembering the moves
when they are alone.  That the work style of a long-time user is a
different one is not that important.

Thanks for caring,

-- 
David Kastrup

Re: guided tour suggestions

[David House]

David Kastrup writes:
 > One of the problems with promoting Emacs nowadays are users who tried it 10
 > years ago and were not getting along with it. Dispelling their (and their
 > audience's) preconceptions is easier with more graphical material.

I think this is worthwhile.

 > I am aware that one of the most frequent customizations is turning off
 > the toolbar in order to maximize screen estate and minimize clutter.
 > For a live showoff of the skills of an experienced user, this might be
 > somewhat feasible.  But as soon as we are getting into (live or
 > off-line) tutorial reign, it becomes a much better idea to show off
 > and use the menus: that way, people have a chance of _following_ what
 > you are doing, and maybe even of doing it by themselves. 

True. If people install Emacs, try to follow along with the tour, then find
their Emacs looks totally different to the one in the screenshots, they're going
to be confused.

Perhaps we could have a little section in the tour showing off how customisable
Emacs is. We could say:

  If you want a more bare-bones Emacs, a good start might be to turn off some of
  the more prominent GUI features.

  [Screenshot showing Custom buffer with settings to turn off scrollbar, menus
  and toolbar, in an Emacs without those features activated.]

  Every single time a different colour or font is used, you can customise which
  one to use:

  [Screenshot showing an Emacs with a white-on-black colour scheme and a
  non-default font.]

  These are just the GUI customisations. Here's a selection of the other things
  you can change: 
  
  * Every single key binding in every single mode can be remapped, including
    mouse sequences.
  * You can redefine any function or command by writing Emacs Lisp.
  [... a few more things here]

  Because all of these options can be overwhelming, Emacs provides a powerful
  configuration interface, M-x custom:

  [Screenshot of the top Custom group.]

  http://emacswiki.org also contains a veritable library of common and
  not-so-common customisations.

Or something of the sort. I think this is an important part of Emacs we should
try to convey.

-- 
-David House, dmhouse@gmail.com

Re: guided tour suggestions

[David Kastrup]

David House <dmhouse@gmail.com> writes:

> Perhaps we could have a little section in the tour showing off how
> customisable Emacs is. We could say:
>
>   If you want a more bare-bones Emacs, a good start might be to turn
>   off some of the more prominent GUI features.
>
>   [Screenshot showing Custom buffer with settings to turn off
>   scrollbar, menus and toolbar, in an Emacs without those features
>   activated.]

Personally, I find this irrelevant for a tour.  A single sentence "All
of the graphical and other features can be customized and also turned
off if desired" is sufficient.

If we really _must_ show anything in that respect, a customize buffer
is not really convincing.  Instead, the Options/Show/Hide menu would
be more appropriate.

>   Every single time a different colour or font is used, you can
>   customise which one to use:
>
>   [Screenshot showing an Emacs with a white-on-black colour scheme
>   and a non-default font.]

It is actually not much of a selling point: most people just assume
that they can configure stuff like that.

>   These are just the GUI customisations. Here's a selection of the
>   other things you can change:
>   
>   * Every single key binding in every single mode can be remapped, including
>     mouse sequences.
>   * You can redefine any function or command by writing Emacs Lisp.
>   [... a few more things here]
>
>   Because all of these options can be overwhelming, Emacs provides a powerful
>   configuration interface, M-x custom:
>
>   [Screenshot of the top Custom group.]
>
>   http://emacswiki.org also contains a veritable library of common and
>   not-so-common customisations.
>
> Or something of the sort. I think this is an important part of Emacs we should
> try to convey.

Maybe.  We should not overdo this aspect.  After all, one _can_ work
reasonably well with the default settings.  Customizing Emacs is
something for which the desire will only come with some time of usage.

-- 
David Kastrup

Re: guided tour suggestions

[Phil Sung]

David Kastrup <dak@gnu.org> writes:
>> When I get a chance, I will make some screenshots with the default
>> UI setup, and with more complex formatting/characters.
>
> Very much appreciated.  One of the problems with promoting Emacs
> nowadays are users who tried it 10 years ago and were not getting
> along with it.  Dispelling their (and their audience's) preconceptions
> is easier with more graphical material.

Sorry for the delay in replying.

<http://stuff.mit.edu/iap/emacs/emacs-guided-tour-1.html>
Changes:

* A couple of screenshots retaken under the default UI setup with GTK-- menu
  bar, toolbar, scroll bars.

* Added screenshot of Emacs displaying the splash screen (includes a picture in
  the buffer).

* More fonts of varying shapes, sizes, and colors (see the auctex and info
  examples).

* Removed shell screenshot from the first section. (M-x shell still gets
  mentioned later.)

--Phil

Re: guided tour suggestions

[David Kastrup]

"Phil Sung" <psung@mit.edu> writes:

> David Kastrup <dak@gnu.org> writes:
>>> When I get a chance, I will make some screenshots with the default
>>> UI setup, and with more complex formatting/characters.
>>
>> Very much appreciated.  One of the problems with promoting Emacs
>> nowadays are users who tried it 10 years ago and were not getting
>> along with it.  Dispelling their (and their audience's) preconceptions
>> is easier with more graphical material.
>
> Sorry for the delay in replying.
>
> <http://stuff.mit.edu/iap/emacs/emacs-guided-tour-1.html>
> Changes:
>
> * A couple of screenshots retaken under the default UI setup with GTK-- menu
>   bar, toolbar, scroll bars.
>
> * Added screenshot of Emacs displaying the splash screen (includes a picture in
>   the buffer).
>
> * More fonts of varying shapes, sizes, and colors (see the auctex and info
>   examples).
>
> * Removed shell screenshot from the first section. (M-x shell still gets
>   mentioned later.)

You pretty much redid all screenshots!  Very nice, this makes it a
page that I can point people to without scaring them off.  The
dimensions of the screen shot make the decorations take away more
relative screen space, but it will always be easier for someone to
imagine one can take them away rather than that one can add them (and
I'd actually keep the follow-mode shot, where screen estate is
particularly important, pretty much as you did it).

So the cumulative "scare-away" factor taken over all potential users
should now be much less in my opinion.  Thanks for creating the page
in the first place, and for following up on the suggestions.

-- 
David Kastrup

Re: guided tour suggestions

[Phil Sung]

On 8/9/07, David Kastrup <dak@gnu.org> wrote:
> So the cumulative "scare-away" factor taken over all potential users
> should now be much less in my opinion.  Thanks for creating the page
> in the first place, and for following up on the suggestions.

Thanks, all, for your suggestions!

I've sent a patch to webmasters@gnu.org.

--Phil

Re: guided tour suggestions

[Nick Roberts]

 > > Would it be possible to make the screenshots with emacs -Q so that people
 > > see what they get out of the box ... ?
 > 
 > Good idea.
 > 
 > > The guided tour ... shows an Emacs a) compiled without a modern toolkit
 > > (Gtk+, Windows or Mac) b) without menus c) without toolbars d) without
 > > scrollbars (for heaven's sake!) e) without font diversity. The only thing
 > > hinting at fonts is a man-page f) without file dialogs g) without tooltips h)
 > > without any non-ASCII character
 > 
 > When I get a chance, I will make some screenshots with the default UI setup,
 > and with more complex formatting/characters.

Remember, however, that GTK is _not_ the default toolkit for Emacs 22.1 so that
won't be what people see out of the box.  Currently it won't be the default for
Emacs 22.2 either.

-- 
Nick                                           http://www.inet.net.nz/~nickrob

Re: guided tour suggestions

[David Kastrup]

Nick Roberts <nickrob@snap.net.nz> writes:

>  > > Would it be possible to make the screenshots with emacs -Q so
>  > > that people see what they get out of the box ... ?
>  > 
>  > Good idea.
>  > 
>  > > The guided tour ... shows an Emacs a) compiled without a modern
>  > > toolkit (Gtk+, Windows or Mac) b) without menus c) without
>  > > toolbars d) without scrollbars (for heaven's sake!) e) without
>  > > font diversity. The only thing hinting at fonts is a man-page
>  > > f) without file dialogs g) without tooltips h) without any
>  > > non-ASCII character
>  > 
>  > When I get a chance, I will make some screenshots with the
>  > default UI setup, and with more complex formatting/characters.
>
> Remember, however, that GTK is _not_ the default toolkit for Emacs
> 22.1 so that won't be what people see out of the box.

Depends on the box.  I should hope that at least GNOME-centric
distributions with X11 would offer the Gtk+ version (Debian offers a
choice IIRC of what to install).  Anyway, if we wanted to go for "most
common case", we would need to show a Windows Emacs.  That is not
really what we want, either (though a single screenshot for each of
the major platforms for comparison would perhaps be nice: I find that
Emacs' visual integration into various desktops is a selling point
against XEmacs which shows quite the same quaint look everywhere), but
I suppose it pretty much depends on who is going to spend the effort
of creating the screenshots.

> Currently it won't be the default for Emacs 22.2 either.

I think there is still a difference between using configure without
options, and using no run-time options.  However, I would also
consider my compilation (using --without-toolkit-scroll-bars since
anything but Athena toolkit semantics is somewhat dysfunctional) unfit
for screen shots since it uses _special_ configure options resulting
in a look that won't likely be available "out of the box" for _any_
distribution.  It would be too complicated explaining that my look
does not result from a deficiency of Emacs, but a deficiency of Gtk+
and my way around it (with a little bit of help from Emacs).

-- 
David Kastrup

Re: guided tour suggestions

[Juri Linkov]

>> The guided tour ... shows an Emacs a) compiled without a modern toolkit
>> (Gtk+, Windows or Mac) b) without menus c) without toolbars d) without
>> scrollbars (for heaven's sake!) e) without font diversity. The only thing
>> hinting at fonts is a man-page f) without file dialogs g) without tooltips h)
>> without any non-ASCII character
>
> When I get a chance, I will make some screenshots with the default UI setup,
> and with more complex formatting/characters.

I think you don't need to redo your existing screenshots that demonstrate
some particular Emacs features, because visual sugar (menus, toolbars and
scrollbars) are irrelevant for these features.  What you need is an
additional screenshot where Emacs GTK is started with `-q' and without `-Q'
because it would be a good idea to make the screenshot from the splash
screen where menus, toolbars and scrollbars are still visible.

-- 
Juri Linkov
http://www.jurta.org/emacs/

Re: guided tour suggestions

[Nick Roberts]

If you're still working on this here are a few thoughts about the screenshot
of Emacs using GDB:

* You could show the toolbar as this is useful for stepping, printing values,
  moving up and down the stack.
* You've deleted the GUD buffer, but it would be better to show this as it's
  fairly fundamental.

I have a screenshot at http://www.inet.net.nz/~nickrob/gdb-ui.png
which also shows the speedbar being used for watch expressions.  I'm not
suggesting that you use this image, though, as it's probably too busy.


-- 
Nick                                           http://www.inet.net.nz/~nickrob

Re: guided tour suggestions

[David House]

Nick Roberts writes:
 > I have a screenshot at http://www.inet.net.nz/~nickrob/gdb-ui.png
 > which also shows the speedbar being used for watch expressions.  I'm not
 > suggesting that you use this image, though, as it's probably too busy.

Really the entire point of IDE shots like this one is to show off as many
features as possible within a single screenshot, so I'd say this image isn't too
busy at all; rather it's perfect.

-- 
-David House, dmhouse@gmail.com

Re: guided tour suggestions

[Dieter Wilhelm]

David House <dmhouse@gmail.com> writes:

> Nick Roberts writes:
>  > I have a screenshot at http://www.inet.net.nz/~nickrob/gdb-ui.png
>  > which also shows the speedbar being used for watch expressions.  I'm not
>  > suggesting that you use this image, though, as it's probably too busy.
>
> Really the entire point of IDE shots like this one is to show off as many
> features as possible within a single screenshot, so I'd say this image isn't too
> busy at all; rather it's perfect.

Right, the subtitle of the guided tour is just "The many faces of
Emacs".

-- 
    Best wishes

    H. Dieter Wilhelm
    Darmstadt, Germany

Re: guided tour suggestions

[David Koppelman]

karl@freefriends.org (Karl Berry) writes:

> We received this report on webmasters (thanks Daniel) ...
>
>
> From: daniel@brockman.se
>
> I am reading the newly-installed Emacs guided tour[1] and
> taking notes as I go along.
>
> Fifth, this
>
>     M-x shell      New shell buffer
>     C-u M-x shell  New shell buffer with specified name
>
> should probably look like this:
>
>     M-x shell      Switch to shell buffer
>     C-u M-x shell  Make new shell buffer

But M-x shell can create a shell buffer, and is certainly the
easier way to do so if you're not picky about names and only need one.
How about:

M-x shell      Create or just switch to shell buffer named *shell*
C-u M-x shell  Create shell buffer with specified name

Re: guided tour suggestions

[Daniel Brockman]

David Koppelman <koppel@ece.lsu.edu> writes:

>>     M-x shell      Switch to shell buffer
>>     C-u M-x shell  Make new shell buffer
>
> But M-x shell can create a shell buffer, and is certainly the
> easier way to do so if you're not picky about names and only need one.

Good point.

> How about:
>
> M-x shell      Create or just switch to shell buffer named *shell*
> C-u M-x shell  Create shell buffer with specified name

Yeah, that's better.

Maybe even this:

   M-x shell      Create or switch to shell buffer named *shell*
   C-u M-x shell  Create or switch to shell buffer named as specified

(I think it's both clearer and more precise.)

-- 
Daniel Brockman <daniel@brockman.se>

Re: guided tour suggestions

[Dieter Wilhelm]

karl@freefriends.org (Karl Berry) writes:

>     M-x calc    An RPN calculator.
>
> maybe it is better to mention `M-x calculator' instead?
>

I would rather mention calc because I think that the more mathematical
inclined people (programmers?, majority of Emacs users?) prefere RPN
style calculators and I would also hint the keyboard shortcut 'C-x *
*' for calc.

-- 
    Best wishes

    H. Dieter Wilhelm
    Darmstadt, Germany

Re: guided tour suggestions

[Eli Zaretskii]

> From: Dieter Wilhelm <dieter@duenenhof-wilhelm.de>
> Date: Fri, 04 May 2007 07:09:26 +0200
> Cc: daniel@brockman.se, emacs-devel@gnu.org
> 
> karl@freefriends.org (Karl Berry) writes:
> 
> >     M-x calc    An RPN calculator.
> >
> > maybe it is better to mention `M-x calculator' instead?
> >
> 
> I would rather mention calc because I think that the more mathematical
> inclined people (programmers?, majority of Emacs users?) prefere RPN
> style calculators and I would also hint the keyboard shortcut 'C-x *
> *' for calc.

How about mentioning both, and saying a few words that will allow a
user decide which one they would like to try first?

Re: guided tour suggestions

[Randal L. Schwartz]

>>>>> "Karl" == Karl Berry <karl@freefriends.org> writes:

Karl> Second, this seems like an overstatement (Perl has quite a
Karl> lot of regexp constructs):

Karl>     Emacs regexps support a superset of Perl's regexp constructs.

Karl> As just one example, Emacs doesn't support negative lookahead.

That statement was true in the Perl4 days (back over a decade ago).  Perl5
added a huge pile of new features to regexen, and continues to make
incremental changes on each new release (the upcoming 5.10 will have named
captures, for example).

          Emacs regexps are comparable to regexps available in other
          widely-available languages and tools.

This is a bit of a weaselword, since *everything* is "comparable". :)

-- 
Randal L. Schwartz - Stonehenge Consulting Services, Inc. - +1 503 777 0095
<merlyn@stonehenge.com> <URL:http://www.stonehenge.com/merlyn/>
Perl/Unix/security consulting, Technical writing, Comedy, etc. etc.
See PerlTraining.Stonehenge.com for onsite and open-enrollment Perl training!