From: Phil Sung <psung@MIT.EDU>
To: Chong Yidong <cyd@mit.edu>
Cc: David House <dmhouse@gmail.com>,
mathias.dahl@gmail.com, drew.adams@oracle.com,
emacs-devel@gnu.org
Subject: Re: guided tour suggestions
Date: Mon, 11 Jun 2007 16:01:09 -0400 [thread overview]
Message-ID: <87vedus1kq.fsf@phil.mit.edu> (raw)
In-Reply-To: <87k5umdqos.fsf@stupidchicken.com> (Chong Yidong's message of "Sat\, 02 Jun 2007 16\:52\:51 -0400")
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
next prev parent reply other threads:[~2007-06-11 20:01 UTC|newest]
Thread overview: 32+ messages / expand[flat|nested] mbox.gz Atom feed top
2007-05-03 18:03 guided tour suggestions Karl Berry
2007-05-03 20:34 ` Phil Sung
2007-06-02 20:52 ` Chong Yidong
2007-06-02 21:04 ` David Kastrup
2007-06-02 22:08 ` Drew Adams
2007-06-03 8:23 ` Mathias Dahl
2007-06-03 15:32 ` David House
2007-06-11 20:01 ` Phil Sung [this message]
2007-06-11 20:19 ` Drew Adams
2007-06-27 1:16 ` Phil Sung
2007-06-27 4:28 ` Drew Adams
2007-06-27 5:45 ` David Kastrup
2007-06-27 6:04 ` Nick Roberts
2007-06-27 7:37 ` David Kastrup
2007-06-28 7:02 ` Phil Sung
2007-06-28 7:20 ` David Kastrup
2007-06-28 9:54 ` David House
2007-06-28 10:25 ` David Kastrup
2007-08-09 7:15 ` Phil Sung
2007-08-09 7:36 ` David Kastrup
2007-08-13 8:09 ` Phil Sung
2007-06-28 8:20 ` Nick Roberts
2007-06-28 8:36 ` David Kastrup
2007-06-29 16:41 ` Juri Linkov
2007-06-30 1:16 ` Nick Roberts
2007-06-30 10:03 ` David House
2007-07-22 10:59 ` Dieter Wilhelm
2007-05-03 22:30 ` David Koppelman
2007-05-03 22:41 ` Daniel Brockman
2007-05-04 5:09 ` Dieter Wilhelm
2007-05-04 7:32 ` Eli Zaretskii
2007-05-05 14:39 ` Randal L. Schwartz
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.gnu.org/software/emacs/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87vedus1kq.fsf@phil.mit.edu \
--to=psung@mit.edu \
--cc=cyd@mit.edu \
--cc=dmhouse@gmail.com \
--cc=drew.adams@oracle.com \
--cc=emacs-devel@gnu.org \
--cc=mathias.dahl@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).