all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
* Tutorial incorrectly thinks emacs -Q uses customizations. Alarmist and confusing tutorial intro.
@ 2007-01-27 19:23 Drew Adams
  2007-01-28  1:37 ` Lennart Borgman (gmail)
                   ` (2 more replies)
  0 siblings, 3 replies; 8+ messages in thread
From: Drew Adams @ 2007-01-27 19:23 UTC (permalink / raw)
  To: Emacs-Pretest-Bug, Emacs-Devel

emacs -Q
Help > Emacs Tutorial

You see this, in red, at the top:

 NOTICE: The main purpose of the Emacs tutorial is to teach you
 the most important standard Emacs commands (key bindings).
 However, your Emacs has been customized by changing some of
 these basic editing commands, so it doesn't correspond to the
 tutorial.  We have inserted colored notices where the altered
 commands have been introduced. [More]

This is wrong - nothing has been customized in emacs -Q.

The wording is also bad: "standard Emacs commands" are not the same
thing as "key bindings".  So already we're teaching the vocabulary
incorrectly.

"has been customized by changing some of these basic editing
commands".  Customizing a key binding doesn't change a command.
The wording is not good.

"We have inserted colored notices" sounds horrible too.  Who's "we"?
The user is just following a tutorial; it is only the tutorial that
should be speaking to the user - there is no need of 1) the user, 2)
the tutorial, and 3) some "we" who comments about modifications "they"
made to the tutorial by "inserting colored notices".

If this doesn't appear to users to be an UGLY hack, then I don't know what
would.

If the idea is to adapt the tutorial so that it reflects the user's
customized key bindings, then that is done poorly (or not at all).
Similarly, if the idea is to mark all of the places in the tutorial
that mention standard bindings that are not currently in effect
because of customization.

I really think this hack does more harm than good, at least the way
it's done now.  Just say that the tutorial reflects the standard Emacs
bindings.  That's all.  "We" are trying to be too clever, and it hurts
the user.

Anyway... Clicking [More] then shows this:

 The following key bindings used in the tutorial had been changed
 from the Emacs default in the TUTORIAL (English) buffer:

   Key       Standard Binding            Is Now On   Remark
   <M-backspace> backward-kill-word      <C-backspace> more info
   <backspace> delete-backward-char      DEL         more info

 It is OK to change key bindings, but changed bindings do not
 correspond to what the tutorial says.

This is also wrong: "had been changed" is incorrect grammatically
here.  Perhaps "have" was meant.  What is the point of "from the Emacs
default in the TUTORIAL (English) buffer"?  Buffer?  English?  Why is
TUTORIAL uppercase?  I don't understand this sentence AT ALL.  What
are we trying to say here?  And why are we telling the user that s?he
can change bindings? (during the tutorial? in the future? in the past?)

The help shown from clicking [More] is also not aligned well, as can
be seen above.

It is also unclear: What does "Is Now On" mean?  What is now on what?
Does it mean that the Standard Binding (command), which is the second
column, is now on that key?  The order seems backward (German? ;-)).
The order should be:

Command             Current Key    Standard Key (emacs -Q)
-------             -----------    -----------------------
backward-kill-word  <C-backspace>  <M-backspace>

Or, better perhaps (depending on what the intention is - I'm lost):

Key mentioned in tutorial  Key in your Emacs  Command
-------------------------  -----------------  -------
<M-backspace>              <C-backspace>      backward-kill-word

In any case, however this is done, it is bound to confuse.

Another bug, unrelated to the tutorial: Clicking `delete-backward-char' does
not show its binding (DEL).  The doc string needs to mention this.

Clicking either of the "more info" links leads to further incorrect
information...

Most importantly:

Do we really need this?  What is the point of scaring users with a
huge red "NOTICE", and inviting them to click for more information
that details ALL of the bindings that are different from the default
bindings.  (Not to mention that it does so erroneously.)

This is crazy.  This is the FIRST thing that a newbie will see, when
trying to learn about Emacs.  It sends only one message: "You will
never understand Emacs.  It is far too difficult for you to learn.
You can't even figure out what we're trying to say about customized
bindings.  What a dummy you are - move along."

Please, let's drop this or redo it completely.  If we keep it, it
needs to be 1) simple, 2) unalarming, 3) obviously of secondary
importance.  A tutorial should hold you by the hand in the beginning,
not scare and confuse you.

^ permalink raw reply	[flat|nested] 8+ messages in thread

end of thread, other threads:[~2007-01-29  5:38 UTC | newest]

Thread overview: 8+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2007-01-27 19:23 Tutorial incorrectly thinks emacs -Q uses customizations. Alarmist and confusing tutorial intro Drew Adams
2007-01-28  1:37 ` Lennart Borgman (gmail)
2007-01-28  2:26   ` Drew Adams
2007-01-28  3:43   ` Chris Moore
2007-01-28 11:34     ` Lennart Borgman (gmail)
2007-01-29  5:38   ` Richard Stallman
2007-01-28  7:41 ` Richard Stallman
2007-01-28 11:35 ` Johan Bockgård

Code repositories for project(s) associated with this external index

	https://git.savannah.gnu.org/cgit/emacs.git
	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.