Document option tool-bar-mode

Document option tool-bar-mode

[Bill Wohler]

Any objection to the following patch?

Index: frames.texi
===================================================================
RCS file: /cvsroot/emacs/emacs/man/frames.texi,v
retrieving revision 1.94
diff -u -u -r1.94 frames.texi
--- frames.texi	10 Oct 2005 15:00:57 -0000	1.94
+++ frames.texi	18 Dec 2005 01:19:26 -0000
@@ -963,7 +963,7 @@
 bar uses monochrome icons (PBM or XBM format).
 
   You can turn display of tool bars on or off with @kbd{M-x
-tool-bar-mode}.
+tool-bar-mode} or by customizing the option @samp{tool-bar-mode}.
 
 @node Dialog Boxes
 @section Using Dialog Boxes

-- 
Bill Wohler <wohler@newt.com>  http://www.newt.com/wohler/  GnuPG ID:610BD9AD
Maintainer of comp.mail.mh FAQ and MH-E. Vote Libertarian!
If you're passed on the right, you're in the wrong lane.

Re: Document option tool-bar-mode

[Luc Teirlinck]

Bill Wohler wrote: 

      You can turn display of tool bars on or off with @kbd{M-x
   -tool-bar-mode}.
   +tool-bar-mode} or by customizing the option @samp{tool-bar-mode}.

The two things above are described as equivalent, but they are not.
The first is strictly for the current session, the second is usually
meant to be permanent.  It is @code{tool-bar-mode}, not @samp.
`customizing' is ambiguous.  It does not consistently refer to the
Customize interface, but is often used in a more general sense.

I prefer the following patch, where the word `variable' still could be
replaced by `option', depending on what we decide in another
discussion.   It only talks about turning toolbars _off_ permanently,
because they are enabled by default in all situations where they make
sense.

      You can turn display of tool bars on or off with @kbd{M-x
    tool-bar-mode}.  You can turn tool bars permanently off by putting the
    line @code{(tool-bar-mode 0)} in your @file{.emacs} file, or by saving
    the variable @code{tool-bar-mode} through the Customize interface.

Sincerely,

Luc.

Re: Document option tool-bar-mode

[Bill Wohler]

Luc Teirlinck <teirllm@dms.auburn.edu> wrote:

> Bill Wohler wrote: 
> 
>       You can turn display of tool bars on or off with @kbd{M-x
>    -tool-bar-mode}.
>    +tool-bar-mode} or by customizing the option @samp{tool-bar-mode}.
> 
> The two things above are described as equivalent, but they are not.
> The first is strictly for the current session, the second is usually
> meant to be permanent.  It is @code{tool-bar-mode}, not @samp.

Thanks.

> `customizing' is ambiguous.  It does not consistently refer to the
> Customize interface, but is often used in a more general sense.

Perhaps we should not do that. "Customizing the option foo" is much
cleaner than "saving the variable foo through the Customize interface."

> I prefer the following patch, where the word `variable' still could be
> replaced by `option', depending on what we decide in another
> discussion.   It only talks about turning toolbars _off_ permanently,
> because they are enabled by default in all situations where they make
> sense.
> 
>       You can turn display of tool bars on or off with @kbd{M-x
>     tool-bar-mode}.  You can turn tool bars permanently off by putting the
>     line @code{(tool-bar-mode 0)} in your @file{.emacs} file, or by saving
>     the variable @code{tool-bar-mode} through the Customize interface.

A couple of small grammar tweaks:

       You can turn display of tool bars on or off with @kbd{M-x
     tool-bar-mode}. You can turn tool bars off permanently by putting
     the line @code{(tool-bar-mode 0)} in your @file{.emacs} file, or by
     setting and saving the variable @code{tool-bar-mode} through the
     Customize interface.

I still think that "customizing the option @code{tool-bar-mode}" is much
better.

-- 
Bill Wohler <wohler@newt.com>  http://www.newt.com/wohler/  GnuPG ID:610BD9AD
Maintainer of comp.mail.mh FAQ and MH-E. Vote Libertarian!
If you're passed on the right, you're in the wrong lane.

Re: Document option tool-bar-mode

[Luc Teirlinck]

Bill Wohler wrote:

   > `customizing' is ambiguous.  It does not consistently refer to the
   > Customize interface, but is often used in a more general sense.

   Perhaps we should not do that. "Customizing the option foo" is much
   cleaner than "saving the variable foo through the Customize interface."

You can customize various things in your .emacs, including keybindings.
This would be irrelevant if `(setq tool-bar-mode nil)' worked too, but
since it does not, it is good to emphasize that you must set the
variable _through the Customize interface_.

Sincerely,

Luc.

Re: Document option tool-bar-mode

[Bill Wohler]

Luc Teirlinck <teirllm@dms.auburn.edu> wrote:

> Bill Wohler wrote:
> 
>    > `customizing' is ambiguous.  It does not consistently refer to the
>    > Customize interface, but is often used in a more general sense.
> 
>    Perhaps we should not do that. "Customizing the option foo" is much
>    cleaner than "saving the variable foo through the Customize interface."
> 
> You can customize various things in your .emacs, including keybindings.
          ^^^^^^^^
Yeah, there's not really a better term for that other than customize.

OK, so let's allow customize as the general term (customizing through
.emacs or through the Customize interface). We can then define
"customize the option foo" to mean "use the Customize interface to set
and save option foo." Similarly for "customize the face foo." An
advanced user will be happy to interpret these phrases as he wishes.
Furthermore, we define "customizable" to refer to an option or face that
can be modified through the Customize interface.

We just need to make sure there aren't phrases like "customize the
option foo" when "foo" doesn't have a Customize interface.

-- 
Bill Wohler <wohler@newt.com>  http://www.newt.com/wohler/  GnuPG ID:610BD9AD
Maintainer of comp.mail.mh FAQ and MH-E. Vote Libertarian!
If you're passed on the right, you're in the wrong lane.

Re: Document option tool-bar-mode

[Luc Teirlinck]

Bill Wohler wrote:

   We can then define "customize the option foo" to mean "use the
   Customize interface to set and save option foo." Similarly for
   "customize the face foo." An advanced user will be happy to
   interpret these phrases as he wishes.  Furthermore, we define
   "customizable" to refer to an option or face that can be modified
   through the Customize interface.

`customize' is a general English word, not some technical term.  Let
me repeat for emphasis: there is no problem _unless_ customizing the
variable _only_ takes effect when set through Custom.  In such a
situation, it is good to be emphatic and unambiguous.

Sincerely,

Luc.

Re: Document option tool-bar-mode

[Richard M. Stallman]

    `customize' is a general English word, not some technical term.  Let
    me repeat for emphasis: there is no problem _unless_ customizing the
    variable _only_ takes effect when set through Custom.  In such a
    situation, it is good to be emphatic and unambiguous.

I agree with both points.

Re: Document option tool-bar-mode

[Richard M. Stallman]

    >       You can turn display of tool bars on or off with @kbd{M-x
    >    -tool-bar-mode}.
    >    +tool-bar-mode} or by customizing the option @samp{tool-bar-mode}.
    > 
    > The two things above are described as equivalent, but they are not.
    > The first is strictly for the current session, the second is usually
    > meant to be permanent.

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.

Re: Document option tool-bar-mode

[Bill Wohler]

Richard M. Stallman <rms@gnu.org> wrote:

>                                           Let's use Bill's shorter
> text.

Done.

-- 
Bill Wohler <wohler@newt.com>  http://www.newt.com/wohler/  GnuPG ID:610BD9AD
Maintainer of comp.mail.mh FAQ and MH-E. Vote Libertarian!
If you're passed on the right, you're in the wrong lane.

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.

Re: Document option tool-bar-mode

[Richard M. Stallman]

	 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 don't think this is a problem.  The user will probably
look at the chapter on customization and find various ways
to do it.

Re: Document option tool-bar-mode

[Luc Teirlinck]

Richard Stallman wrote:

	    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 don't think this is a problem.  The user will probably
   look at the chapter on customization and find various ways
   to do it.

Except that not all of these ways work in this case.  The one he
probably already knows does not.  I should have mentioned that setting
`partial-completion-mode' (and `tool-bar-mode') _only_ works when set
through Custom.

Sincerely,

Luc.

Re: Document option tool-bar-mode

[Richard M. Stallman]

	   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 don't think this is a problem.  The user will probably
       look at the chapter on customization and find various ways
       to do it.

    Except that not all of these ways work in this case.  The one he
    probably already knows does not.  I should have mentioned that setting
    `partial-completion-mode' (and `tool-bar-mode') _only_ works when set
    through Custom.

If this case is of that kind, then I agree it should mention M-x
customize explicitly.