Re: Document option tool-bar-mode

[Luc Teirlinck]

Richard Stallman wrote:

   Not necessaily.  You can set variables either temporarily or permanently
   with Custom.  So I think Bill's text is not wrong (aside from @samp).

   We're talking to people here, not to machines.  If people won't get
   the wrong idea, it isn't a problem.  Meanwhile, making the text longer
   and more cumberson would impede clarity.  Let's use Bill's shorter
   text.

If you do `C-h i g (emacs)Intro' and then do
`s customize RET s RET s RET...',
you will see that "customize" is used in the general English sense of
the word and even _explicitly_ in the sense of setting variables in the
non Custom way when we suddenly see:

     To enable this mode, use the command `M-x partial-completion-mode',
    or customize the variable `partial-completion-mode'.

But at this stage the Customize interface has not even been mentioned.
How could a user new to Emacs, who reads the manual back to front,
understand this any other way than to set the variable without using
Custom?  He does not even know about Custom's existence yet.

I believe that there is not only a problem with Bill's text, there is
also a problem with the above quote, as well as with similar usage
elsewhere in the Emacs manual.  How can a beginning user guess that
"customize" means customize through some specific interface, when he
is not even aware of the existence of that interface yet?

I believe that the Emacs manual is not meant exclusively as an online
reference for experienced users and we should not treat it as such.
(Unfortunately, many people on this list seem to view it exclusively
as an online reference, because that is how they themselves use it.)

Sincerely,

Luc.