Re: guided tour suggestions

[Phil Sung <psung@MIT.EDU>]

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