Tutorial incorrectly thinks emacs -Q uses customizations. Alarmist and confusing tutorial intro.

Tutorial incorrectly thinks emacs -Q uses customizations. Alarmist and confusing tutorial intro.

[Drew Adams]

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.

Re: Tutorial incorrectly thinks emacs -Q uses customizations. Alarmist and confusing tutorial intro.

[Lennart Borgman (gmail)]

Drew Adams wrote:
> 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.


It is a bug. I have noticed it and have a fix for it, but I have not had 
time to send it to the list yet.


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


Could you please propose a better text?


> 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.


I am not quite sure "had" is incorrect here. The state of the TUTORIAL 
buffer may have changed since the link was created. Is not "had" the 
correct word then? Or how would you say it?


>  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.


Would it be more understandable like this

    from the Emacs default in the buffer "TUTORIAL (English)":

"TUTORIAL (English)" is simply the name of the tutorial buffer.

Or maybe it is better just to say

    from the Emacs default:

Even if this is more inexact it is actually not incorrect.


> 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?)


These text should only be showed if some of the key bindings used in the 
tutorial have been changed. In other words they are only showed when the 
tutorial does not work.

We discussed what to do in this case earlier. We decided then that the 
best way to handle it was to tell the user about the problem. Other 
alternatives was to refuse to run the tutorial or to change the key 
bindings in the tutorial buffer so that they matched the tutorial.


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


Some more work can be done on this. It fails with very long names if I 
remember correctly now. But I felt this was good enough.


> 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.


I am not sure what is best. Of your proposals I like the first one best. 
  What do others think?


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


This is disturbing but maybe a bit hard to fix right now. I would rather 
put that in TO-DO for after the release.


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


Please tell what the incorrect information is.


> 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 was my idea so I guess I have to say something about it.

Yes, I believe we need it. The idea is simply to tell the user let the 
user run the tutorial even though some things have changed, but inform 
the user what has changed. I think without this the user may get very 
confused when the tutorial does not work.

Whether this is the best way to handle the problem with changed key 
bindings that affects the tutorial is another question (see above).


> This is crazy.  This is the FIRST thing that a newbie will see, when
> trying to learn about Emacs.


If no key bindings have been changed the user will not see this. (When 
the bug has been fixed.)


> 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.


IMO this is the wrong level to discuss it on. We should rather discuss 
the GUI instead and how that can be used to teach the user Emacs. After 
the release of course.

RE: Tutorial incorrectly thinks emacs -Q uses customizations. Alarmist and confusing tutorial intro.

[Drew Adams]

> Could you please propose a better text?

As I said, I prefer that we not use this.  I think it has a negative effect.

> I am not quite sure "had" is incorrect here. The state of the TUTORIAL
> buffer may have changed since the link was created. Is not "had" the
> correct word then? Or how would you say it?

I wouldn't say it. I would just say something generic, without trying to
determine whether the user had actually customized Emacs. Something short
and simple, such as this:

"Keys mentioned in this tutorial are those defined by default. If Emacs has
been customized, then some keys might differ from those mentioned here. If
you want to use the tutorial with the standard Emacs keys, then start Emacs
again using `emacs -Q'."

IOW, "YMMV".

This need not be in red, and it need not be the very first thing the user
reads. It should not be. Put it after the first place where the tutorial
asks you to use a key, as a footnote. "YMMV" belongs in the fine print (more
or less).

> These text should only be showed if some of the key bindings used in the
> tutorial have been changed. In other words they are only showed when the
> tutorial does not work.

I don't agree that that is worthwhile. Just let users know that the tutorial
is written for standard (i.e. default) Emacs bindings. That's all.

The tutorial should not (IMO) be mostly about teaching keys, anyway. If it
is, then that's a mistake. Keys are only a means to Emacs functionalities;
we shouldn't concentrate too much on them.

Users can learn Emacs using emacs -Q, and they can then learn different
bindings afterward, if need be, for their customized version.

> We discussed what to do in this case earlier. We decided then that the
> best way to handle it was to tell the user about the problem. Other
> alternatives was to refuse to run the tutorial or to change the key
> bindings in the tutorial buffer so that they matched the tutorial.

I think the cure is worse than the disease. There is no reason to refuse to
run the tutorial or to try to adapt it. Just let users know that it assumes
standard (default) bindings. Keep it simple.

Users should get the same behavior each time they use the tutorial, whether
with customized or vanilla Emacs - any other behavior is confusing.
Referential transparency and all...

> Some more work can be done on this. It fails with very long names if I
> remember correctly now. But I felt this was good enough.

It's not needed. I don't think users who have customized versions of Emacs
really need to be told just which bindings have changed. It's true that some
of the tutorial won't "work" or even make sense to them without knowing
which keys to use, but it should be clear that they can always use the
tutorial with emacs -Q. We don't need to make the tutorial work for
customized bindings.

> I am not sure what is best. Of your proposals I like the first one best.
> What do others think?

None of them are needed. I shouldn't even have mentioned them. My point was
that what is there now is harmful, because confusing (and scary).

> > Another bug, unrelated to the tutorial: Clicking
> > `delete-backward-char' does
> > not show its binding (DEL).  The doc string needs to mention this.
>
> This is disturbing but maybe a bit hard to fix right now. I would rather
> put that in TO-DO for after the release.

`delete-backward-char' is a built-in function. It should be possible to fix
this detail. (Again, it has nothing to do with the tutorial.)

> > Most importantly: Do we really need this?
>
> Yes, I believe we need it. The idea is simply to tell the user let the
> user run the tutorial even though some things have changed, but inform
> the user what has changed. I think without this the user may get very
> confused when the tutorial does not work.

The confusion is 100x now. I see no need for the user to run the tutorial
using customized bindings.

If you could automatically adapt the entire tutorial to reflect the user's
bindings perfectly, then I guess it could be OK (but see above, about same,
repeated behavior). However, that is too difficult, and any half measure is
worse than none at all.

> Whether this is the best way to handle the problem with changed key
> bindings that affects the tutorial is another question (see above).

That's the question. My answer is "No".

> > This is crazy.  This is the FIRST thing that a newbie will see, when
> > trying to learn about Emacs.
>
> If no key bindings have been changed the user will not see this. (When
> the bug has been fixed.)

That bug really needs to be fixed, at a minimum. Right now, we're scaring
100% of the people who try the tutorial 100% of the time. Messing their
minds, to no good end.

> > 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.
>
> IMO this is the wrong level to discuss it on. We should rather discuss
> the GUI instead and how that can be used to teach the user Emacs. After
> the release of course.

Fine, let's discuss the GUI and the tutorial and lots more after the
release. But let's please pull this enhancement now; it's not ready for
prime time.

The last thing we want the tutorial to do is confuse and scare new users.
Emacs already has a reputation for being difficult to learn and use. And
supposed key-binding madness is a big part of that bad rep. The tutorial
should make you feel self-confident, showing you that *YOU CAN* use Emacs
without being a key-binding wizard. If bindings are getting in the way, then
the tutorial has not done its job.

I feel so strongly that it is not mainly about learning keys, that I
wouldn't mind if the tutorial started with just the menu (which requires no
explanation to start using), but we've been down that path before...

Re: Tutorial incorrectly thinks emacs -Q uses customizations. Alarmist and confusing tutorial intro.

[Chris Moore]

"Lennart Borgman (gmail)" <lennart.borgman@gmail.com> writes:

> Drew Adams wrote:

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

> Please tell what the incorrect information is.

I'm guessing it's this:

  The default Emacs binding for the key <M-backspace> is the command
  `backward-kill-word'.  However, your customizations have rebound it to
  the command `nil'.

"the command `nil'"?  `nil' isn't a command!

Re: Tutorial incorrectly thinks emacs -Q uses customizations. Alarmist and confusing tutorial intro.

[Lennart Borgman (gmail)]

Chris Moore wrote:
> "Lennart Borgman (gmail)" <lennart.borgman@gmail.com> writes:
> 
>> Drew Adams wrote:
> 
>>> Clicking either of the "more info" links leads to further incorrect
>>> information...
> 
>> Please tell what the incorrect information is.
> 
> I'm guessing it's this:
> 
>   The default Emacs binding for the key <M-backspace> is the command
>   `backward-kill-word'.  However, your customizations have rebound it to
>   the command `nil'.
> 
> "the command `nil'"?  `nil' isn't a command!


Ah, yes. It is part of the same bug. I initially misunderstood the 
translation key maps and their function versus the key lookup functions.

I think the problem Drew saw only shows up on w32, but I am not quite 
sure. If the tutorial is started after emacs -Q on GNU/Linux, does it 
looks ok then?

Re: Tutorial incorrectly thinks emacs -Q uses customizations. Alarmist and confusing tutorial intro.

[Richard Stallman]

I've made a few minor fixes to a few of these details.
What do you think of them?


*** tutorial.el	28 Jan 2007 02:11:20 -0500	1.13
--- tutorial.el	28 Jan 2007 22:05:09 -0500	
***************
*** 334,343 ****
  				tutorial--default-keys)))))
          (when changed-keys
            (insert
!            "The following key bindings used in the tutorial had been changed
! from the Emacs default in the " (buffer-name tutorial-buffer) " buffer:\n\n" )
!           (let ((frm "   %-9s %-27s %-11s %s\n"))
!             (insert (format frm "Key" "Standard Binding" "Is Now On" "Remark")))
            (dolist (tk changed-keys)
              (let* ((def-fun     (nth 1 tk))
                     (key         (nth 0 tk))
--- 334,344 ----
  				tutorial--default-keys)))))
          (when changed-keys
            (insert
!            "The following key bindings used in the tutorial have been changed
! from the Emacs default:\n\n" )
!           (let ((frm "   %-14s %-27s %-16s\n"))
!             (insert (format frm
! 			    "Standard Key" "Command" "In Your Emacs")))
            (dolist (tk changed-keys)
              (let* ((def-fun     (nth 1 tk))
                     (key         (nth 0 tk))
***************
*** 354,378 ****
                    (put-text-property 0 (length key-txt)
  				     'face 'tutorial-warning-face key-txt))
                  (insert "   " key-txt " ")
!                 (setq tot-len (length key-txt))
!                 (when (> 9 tot-len)
!                   (insert (make-string (- 9 tot-len) ?\s))
!                   (setq tot-len 9))
                  ;; Insert a link describing the old binding:
                  (insert-button def-fun-txt
                                 'value def-fun
                                 'action
!                                (lambda(button) (interactive)
                                   (describe-function
                                    (button-get button 'value)))
                                 'follow-link t)
!                 (setq tot-len (+ tot-len (length def-fun-txt)))
!                 (when (> 36 tot-len)
!                   (insert (make-string (- 36 tot-len) ?\s)))
                  (when (listp where)
                    (setq where "list"))
                  ;; Tell where the old binding is now:
!                 (insert (format " %-11s "
                                  (if (string= "" where)
                                      (format "M-x %s" def-fun-txt)
                                    where)))
--- 355,374 ----
                    (put-text-property 0 (length key-txt)
  				     'face 'tutorial-warning-face key-txt))
                  (insert "   " key-txt " ")
! 		(indent-to 18)
                  ;; Insert a link describing the old binding:
                  (insert-button def-fun-txt
                                 'value def-fun
                                 'action
!                                (lambda (button) (interactive)
                                   (describe-function
                                    (button-get button 'value)))
                                 'follow-link t)
! 		(indent-to 45)
                  (when (listp where)
                    (setq where "list"))
                  ;; Tell where the old binding is now:
!                 (insert (format " %-16s "
                                  (if (string= "" where)
                                      (format "M-x %s" def-fun-txt)
                                    where)))
***************
*** 381,387 ****
                  ;; cua-mode replacements:
                  (insert-button (car remark)
                                 'action
!                                (lambda(b) (interactive)
                                   (let ((value (button-get b 'value)))
                                     (tutorial--describe-nonstandard-key value)))
                                 'value (cdr remark)
--- 377,383 ----
                  ;; cua-mode replacements:
                  (insert-button (car remark)
                                 'action
!                                (lambda (b) (interactive)
                                   (let ((value (button-get b 'value)))
                                     (tutorial--describe-nonstandard-key value)))
                                 'value (cdr remark)

Re: Tutorial incorrectly thinks emacs -Q uses customizations. Alarmist and confusing tutorial intro.

[Richard Stallman]

    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

I fixed that.  I will try to install the change soon.

Re: Tutorial incorrectly thinks emacs -Q uses customizations. Alarmist and confusing tutorial intro.

[Johan Bockgård]

"Drew Adams" <drew.adams@oracle.com> writes:

> 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.

FWIW, I agree completely.

-- 
Johan Bockgård