toolbar conventions

toolbar conventions

[Bill Wohler]

I just wanted to confirm the correct usage of "toolbar" in Emacs. Its
usage is even less consistent than "menu bar."

By the way, I checked both the O'Reilly style guide and the Microsoft
style guide and both agreed on "menu bar" and "toolbar." Given that
technical terms go from two words, to a hyphenated form, to a single
word, it's likely that's what we're seeing here.

Given that, should we be using "toolbar" in both text and code in
anticipation of a future renaming of tool-bar to toolbar?

-- 
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: toolbar conventions

[Richard M. Stallman]

    By the way, I checked both the O'Reilly style guide and the Microsoft
    style guide and both agreed on "menu bar" and "toolbar." Given that
    technical terms go from two words, to a hyphenated form, to a single
    word, it's likely that's what we're seeing here.

Menu bars are older than tool bars, so if it were simply a natural
progression, it is peculiar that it has proceeded faster for
tool bars than for menu bars.

    Given that, should we be using "toolbar" in both text and code in
    anticipation of a future renaming of tool-bar to toolbar?

I tend to think we should treat the two alike.  But there is no rush
to change this; let's leave it alone, for now.

Does anyone have any ideas on the issue of how to use the term
"option"?  That issue is more important--it is not just an issue of
punctuation, it is inconsistent use of a word.  Would someone like to
study the situation and find out which uses occur where?

Re: toolbar conventions

[Luc Teirlinck]

Richard Stallman wrote:
   
   Does anyone have any ideas on the issue of how to use the term
   "option"?  That issue is more important--it is not just an issue of
   punctuation, it is inconsistent use of a word.  Would someone like to
   study the situation and find out which uses occur where?

The name "user option" used to pretty consistently refer to variables,
although occasionally some remarks about them may have applied to
faces too, without this being explicitly mentioned.

It appears that this started to change somewhere around the beginning
of this year, with changes like:

2005-01-30  Richard M. Stallman  <rms@gnu.org>

	    * custom.texi (Easy Customization): Defn of "User Option"
	    now includes faces.  Don't say just "option" when talking
	    about variables.  Do say just "options" to mean "anything
	    customizable".  (Specific Customization): Describe
	    `customize-variable', not `customize-option'.

This appears to be a rather radical change in terminology, especially
when supposedly preparing for a release.  It would require going very
carefully through code and manuals, if we wanted to be consistent.  I
believe that the majority of places in the Emacs code and docs still
use the word "user option" to mean "user variable".

The change would require some getting used to it for existing users,
used to the old terminology.  Even if we consistently change all code
and manuals, use of the old terminology is likely to find its way back
in, through commits from people unaware of the change.  I myself was
unaware of it, until today.  I read through custom.texi, but somehow I
just thought that it used "option" in a loose way, for convenience.

Sincerely,

Luc.

Re: toolbar conventions

[Bill Wohler]

I have been using "option" in the MH-E manual (125 pages and growing)
and code (21k lines) to refer to anything you can customize. I've been
using "variable" for the remaining variables that must be set with setq.

My rationale was that I wanted to differentiate variables that were
customizable. In addition, both customize-option and customize-variable
have "Customize option:" as the prompt (not "Customize user option
variable:").

At the time I started this convention, I was unaware of the term "user
option." However, with my usage, "user option" is redundant.

I haven't looked recently to see the usage trends. But I think my
terminology is clean and unambiguous.

Note that I haven't quite got around to documenting faces. I'm not sure
if it makes sense or not to refer to them as options. If we do, then we
need to modify customize-option to accept a face and pass it off to
customize-face (maybe we should do that anyway). It feels like I'll be
calling them faces, but I haven't thought about how you would
distinguish between faces that can be customized and those that cannot.
I'll be getting to that chapter in about a week and provide more
visceral feedback then.

Thoughts?

-- 
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: toolbar conventions

[Luc Teirlinck]

Bill Wohler wrote:

   If we do, then we need to modify customize-option to accept a face
   and pass it off to customize-face (maybe we should do that anyway).

Would not work:  a face and a variable can have the same name.
(Different name spaces are used for both.)

Sincerely,

Luc.

RE: toolbar conventions

[Drew Adams]

       Does anyone have any ideas on the issue of how to use the term
       "option"?  That issue is more important--it is not just an issue of
       punctuation, it is inconsistent use of a word.  Would someone like to
       study the situation and find out which uses occur where?

    The name "user option" used to pretty consistently refer to variables,
    although occasionally some remarks about them may have applied to
    faces too, without this being explicitly mentioned.

    It appears that this started to change somewhere around the beginning
    of this year, with changes like:

    2005-01-30  Richard M. Stallman  <rms@gnu.org>

    	    * custom.texi (Easy Customization): Defn of "User Option"
    	    now includes faces.  Don't say just "option" when talking
    	    about variables.  Do say just "options" to mean "anything
    	    customizable".  (Specific Customization): Describe
    	    `customize-variable', not `customize-option'.

    This appears to be a rather radical change in terminology, especially
    when supposedly preparing for a release.  It would require going very
    carefully through code and manuals, if we wanted to be consistent.  I
    believe that the majority of places in the Emacs code and docs still
    use the word "user option" to mean "user variable".

    The change would require some getting used to it for existing users,
    used to the old terminology.  Even if we consistently change all code
    and manuals, use of the old terminology is likely to find its way back
    in, through commits from people unaware of the change.  I myself was
    unaware of it, until today.  I read through custom.texi, but somehow I
    just thought that it used "option" in a loose way, for convenience.

Please note that there was a fairly thorough discussion of exactly this
topic on the emacs-pretest list between 2005-01-22 and 2005-01-27 (hence the
log comment by RMS on 1-30).

Please review those messages before continuing this thread. Better that we
should pick up from where we left off discussing the issues involved, than
that we repeat ourselves. New input on previously discussed stuff is
welcome, of course.

Re: toolbar conventions

[Luc Teirlinck]

Drew Adams wrote:

   Please note that there was a fairly thorough discussion of exactly this
   topic on the emacs-pretest list between 2005-01-22 and 2005-01-27 (hence the
   log comment by RMS on 1-30).

A discussion, no matter how thorough, does not update all docs and
code.  The Emacs manual was changed, but not the Elisp manual, which
uses the term "user option" much more often than the Emacs manual, nor
any other manual, nor the Custom interface itself, nor any docstrings,
nor any code, nor any comments, nor any of the countless other stuff
that would need to be updated.   If we want to return to a consistent
terminology, reversing the change would be a lot less work than
consistently implementing it.

Note that with the current Emacs manual terminology talking about "the
option foo" makes no sense.  There could be two options foo: a
variable foo and a possibly unrelated face foo.  Variables and faces
have different name spaces.

Sincerely,

Luc.

RE: toolbar conventions

[Drew Adams]

       Please note that there was a fairly thorough discussion of
       exactly this topic on the emacs-pretest list between 2005-01-22 and
       2005-01-27 (hence the log comment by RMS on 1-30).

    A discussion, no matter how thorough, does not update all docs and
    code.

Of course not. I agree with everything you said in your message, BTW. My
point was simply to inform people of the previous discussion.

I personally feel that this question should be decided _after_ the release,
and we should, for now, just revert to the use of "option" only for user
variables. (Yes, that reversion requires some changes to doc.)

Why wait? Because it is likely, I hope, that we will change some of the
Customize interface for the next (e.g. 22.2 or 23.1) release, and those
changes might have some bearing on the discussion of such terminology.

Richard instead wants to discuss and decide the terminology question now.
Either way, it can be helpful for people to review the previous discussion.

Re: toolbar conventions

[Richard M. Stallman]

    This appears to be a rather radical change in terminology, especially
    when supposedly preparing for a release.

A change in documentation terminology is never radical in the way code
changes can be.

Last January we had far to go before a release.  Getting the
documentation into shape was the main job that needed doing, and I
found out about a problem in the documentation of Customize.  It
needed a simple way to talk about all the things that you can
customize.  I tried redefining the term "option" to mean all kinds of
things that appear in Custom buffers.

The change was never extended to the other manuals, and it seems to be
bigger than I thought.  So I think that choice was a mistake.  We
ought to undo my half-made change.  But we still need to address the
original problem, to find some other solution to the original problem,
some other term for "all the things that can appear in a Custom
buffer."

In January, some people argued for "preference".  We could use that.
Or perhaps "setting".  What do people think of those?  Any other
suggestions?

Re: toolbar conventions

[Luc Teirlinck]

Richard Stallman wrote:

   In January, some people argued for "preference".  We could use that.
   Or perhaps "setting".  What do people think of those?  Any other
   suggestions?

"setting" would work.  The simple alternative "option or face" is not
even _that_ long and in certain contexts one can even just use option
and rely on the fact that it is clear from the context that in this
particular case it applies to faces too.

Sincerely,

Luc.

RE: toolbar conventions

[Drew Adams]

       In January, some people argued for "preference".  We could use that.
       Or perhaps "setting".  What do people think of those?  Any other
       suggestions?

    "setting" would work.

I was the one who mentioned those two terms, but I did not (and I don't
think anyone else did) really argue that we should adopt them. I simply
pointed them out as common terms.

_If_ we decided that we needed another, more general term to encompass both
options (user variables) and faces, then we might adopt such a term.
However, that would just require us to explain one more name, with little
gain in clarity. Remember the view-mode "quit" vs "leave" vs "exit" vs...
fiasco: if we have multiple, similar terms (e.g. option + preference), we
will be constantly explaining.

Also, both "setting" and "preference" have a connotation of persistence,
because only saved preferences are available in most other apps (where those
terms have been used).

I think "option" and "face" are good terms for what they stand for
currently. "User variable" is clearer than "option", but "option" is clear
enough, IMO. ("User option" is redundant, BTW.) This terminology has worked
well in the past, and would continue to do so. I see no real need for a term
that refers to "option or face" - that expression is clear enough and short
enough.

It is of course the _value_ of a variable or the _values_ of a face's
parameters, not the variable or face, that are truly the settings,
preferences, or options, but I think that that is a distinction we need not
make.

    The simple alternative "option or face" is not
    even _that_ long

I agree. It's a good way to refer to such things.

    and in certain contexts one can even just use option
    and rely on the fact that it is clear from the context that in this
    particular case it applies to faces too.

We should avoid that. We gain nothing by it, and we lose clarity. If we
decide to stick with "option" for a user variable, then we should avoid
employing it in a different sense.

And to repeat what I said before: We should not change the terminology
before this release - we should just make sure that "option" means user
variable everywhere (that is, make only corrections, no sea change). We can
revisit the terminology after or along with any changes we might decide to
make to Customize for the next (23) release.

In particular, as has been discussed, we are pretty much in a box now wrt
the common term "customize" (and "customization" etc.) - we are forced to
restrict its use to apply only to Customize. That's not good, but we have no
choice at this point (for this release).

If we do end up making substantial changes to Customize in a future release
(which I hope), we can then see if we also want to try to revisit the
terminology at that point. Then, in the context of Customize, it might make
sense to speak of "settings" or "preferences" (in place of
"customizations"), since Customize has an implied notion of persistence.

Re: toolbar conventions

[Richard M. Stallman]

    I think "option" and "face" are good terms for what they stand for
    currently.

The discussion of Custom has to mention them both together
so much that we need some word for the two together.

I'm not going to write "option and face" over and over.
I'm going to use a single term, even if it has to be "foobar".

user preferences (was RE: toolbar conventions)

[Drew Adams]

        I think "option" and "face" are good terms for what they stand
        for currently.
    
    The discussion of Custom has to mention them both together so much
    that we need some word for the two together.
    
    I'm not going to write "option and face" over and over.  I'm going
    to use a single term, even if it has to be "foobar".


1. "Foobar" is good... ;-)

Seriously - if we _must_ decide this now, then how about this:

 - We keep "option" as a short way to say "user variable", the latter
   being clearer and preferable in discussions of variables of all
   kinds. That is, we do not extend "option" to include "face".

 - We make it clear (this has already been done, IIUC) that "option"
   (= user variable) includes all variables that are user-variable-p,
   not just those that are customizable.

 - We use "preference" for options and faces, stating this clearly
   somewhere. An alternative is "setting" - we could choose either
   "preference" or "setting", or we could choose to use them both,
   interchangeably. At this level of abstraction, the terminology need
   not be so formal, precisely because we're not making much of a
   distinction.

 - We decide to intend to use "preference" in the future, in
   preference to "customizable" and "customization" in the Customize
   UI and in discussions of Customize, when referring to modifying
   anything intended to be modified by a user. (This includes
   non-customizable user-variable-p variables.) We don't bother to
   make doc and UI changes along these lines now, but we choose now
   "preference" as the preferred way to refer to things intended to be
   changed by users.

 - As long as there are non-customizable user-variable-p variables, we
   use "customizable" to mean changeable and savable in the Customize
   UI. This would be the only place where we would use the common root
   "custom" to refer to the Customize UI - that is, we would not, in
   future, use "customize" or "customized" to refer only to the
   Customize UI. We should, in general, avoid using any "custom"-root
   words, because of the potential for confusion. (A shame, for a
   self-advertised extensible and customizable editor, but
   unavoidable, I think.) Again, we don't bother to make any changes
   along these lines now, but we agree to this direction for the
   future.


2. Open question: What to do about non-customizable user-variable-p
variables? Should we try to eliminate these - not only in vanilla
Emacs, but eliminate also their possibility? That is, should we
eliminate `set-variable's sensitivity to `*' in doc strings? It would
certainly simplify the terminology. All user variables would then be
"customizable". But see also #3, below.


3. As I stated long ago, I would like to see Customize move in the
direction of being better integrated with the rest of Emacs. By that,
I mean that users could change preferences in ways other than using
the Customize UI directly, but Customize would nevertheless recognize
(i.e. could be made to recognize) those changes, and would treat them
the same as changes made inside Customize.

This would, in effect, extend Customize so that some of its
functionality could be used outside a Customize buffer.

Examples:

a. `set-variable' (better called `set-option', IMO) could be used as a
   quick replacement for `customize-option' to change the value (but
   not to save, browse, or do other things that you can do in
   Customize). To understand what I mean, don't think in terms of
   non-customizable user variables here; think in terms of
   customizable options. The point is that a command could be used to
   customize something, without the user ever entering the Customize
   UI.

b. (just an illustration; not intended as a proposal for inclusion)
   Command `doremi-face-fg' (in my library doremi-frm.el) lets you
   modify a face's foreground color incrementally (using the arrow
   keys). You never enter the Customize UI. You can directly
   manipulate the color easily until you get what you want. The
   command also tells Customize that the face foreground has been
   modified, so that Customize thinks the modification was done inside
   Customize. The user can then save the setting in Customize. There
   is no inside/outside Customize here: if the user does `M-x
   customize-customized' after the change, then the face state shows
   as "you have set this face, but not saved it...", NOT as "changed
   outside...". Why? Because that reflects just what the user did.

You might say, "That's great functionality, but why not just
incorporate an incremental face-changer like that into the Customize
UI?" The answer is that we might want to do that in some such cases,
but certainly not all. The Customize UI is complex enough. It can't be
expected to deal with all of the possible ways we might want to let
users modify preferences. There might be several different ways that a
user would want to change a face foreground; would we want to
integrate all of them into the Customize UI? Better that we should let
library writers create new interfaces and have those play well with
Customize.

This approach doesn't take away from Customize; it extends it and
makes it more useful, by integrating it better with the rest of
Emacs. Customize would be the central place to make all customization
changes, and it would notice all changes made outside it. The reason
it does not really play that central customization role today is that
it does not play well with changes made outside it.

We should look for more, and better, ways to let users modify their
Emacs experience - we should shoot for ways that involve _direct
manipulation_ more, for instance. We should not try to make Customize
encompass all such modifications. We should instead make Customize
recognize them and play along with them.

Luc and others have pointed out that there are many problematic
aspects to trying to integrate Customize with changes made outside
it. I don't mean to suggest that there are no problems. But we can try
to solve the problems (as Luc has already done, to a great degree),
and we can try to move a little more in the direction of a Customize
that plays well with Emacs.

I would prefer that we discuss this after the release. I mention it
(again) now, because Richard has decided to decide on the terminology
now, and I feel that possible changes to Customize may affect the
terminology discussion (and vice versa).

Re: user preferences (was RE: toolbar conventions)

[Richard M. Stallman]

I've decided to downgrade the feature of user options that are not
customizable, and use the term "settings" for variables and faces
that work with Custom.

RE: user preferences (was RE: toolbar conventions)

[Drew Adams]

    I've decided to downgrade the feature of user options that are not
    customizable, and use the term "settings" for variables and faces
    that work with Custom.

OK.

Could you elaborate on what you mean by "downgrade"? Just what will be done
(changed)? Is this decision for the current release only, or does it affect
policy going forward?

Re: user preferences (was RE: toolbar conventions)

[Richard M. Stallman]

	I've decided to downgrade the feature of user options that are not
	customizable, and use the term "settings" for variables and faces
	that work with Custom.

    OK.

    Could you elaborate on what you mean by "downgrade"? Just what will be done
    (changed)? Is this decision for the current release only, or does it affect
    policy going forward?

In the long run we might get rid of that option, but I have not decided.
For now, it is just that I don't think it is an important concern
for the manual.

Re: user preferences (was RE: toolbar conventions)

[Richard M. Stallman]

    a. `set-variable' (better called `set-option', IMO) could be used as a
       quick replacement for `customize-option' to change the value (but
       not to save, browse, or do other things that you can do in
       Customize). To understand what I mean, don't think in terms of
       non-customizable user variables here; think in terms of
       customizable options. The point is that a command could be used to
       customize something, without the user ever entering the Customize
       UI.

    b. (just an illustration; not intended as a proposal for inclusion)
       Command `doremi-face-fg' (in my library doremi-frm.el) lets you
       modify a face's foreground color incrementally (using the arrow
       keys).

I think these are good ideas, for after the release.

Re: toolbar conventions

[Glenn Morris]

"Richard M. Stallman" wrote:

> original problem, to find some other solution to the original problem,
> some other term for "all the things that can appear in a Custom
> buffer."
>
> In January, some people argued for "preference".  We could use that.
> Or perhaps "setting".  What do people think of those?  Any other
> suggestions?

Use "customizable" as a noun. Or make a compound noun, eg
custom-item/-object/-setting.

If you try and redefine a common term like "setting" to mean "that
which can be customized via the Emacs customize facility", eedjits
such as myself will never remember the "special Emacs meaning".

Re: toolbar conventions

[Bill Wohler]

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

>     By the way, I checked both the O'Reilly style guide and the Microsoft
>     style guide and both agreed on "menu bar" and "toolbar." Given that
>     technical terms go from two words, to a hyphenated form, to a single
>     word, it's likely that's what we're seeing here.
> 
> Menu bars are older than tool bars, so if it were simply a natural
> progression, it is peculiar that it has proceeded faster for
> tool bars than for menu bars.

Interesting observation.

>     Given that, should we be using "toolbar" in both text and code in
>     anticipation of a future renaming of tool-bar to toolbar?
> 
> I tend to think we should treat the two alike.

I think I'd agree. So do we go with "menubar" and "toolbar" in the
future, or "menu bar" and "tool bar"? Given the following stats, and
because we have menu-bar.el and tool-bar.el already, I'd say the inertia
clearly indicates that "menu bar" and "tool bar" would be the desired
choices for Emacs.

I can add a Style Guide subheading to (elisp)Coding Conventions and
(elisp)Documentation Tips and include this information if you like.

    [wohler@olgas:586]$ grep -ri menubar --exclude \*.elc * --exclude ChangeLog\* --exclude loaddefs.el --exclude ldefs-boot.el| wc
	241    2060   23519
    [wohler@olgas:587]$ grep -ri menu.bar --exclude \*.elc * --exclude ChangeLog\* --exclude loaddefs.el --exclude ldefs-boot.el| wc
       1523    8660  109482
    [wohler@olgas:588]$ grep -ri toolbar --exclude \*.elc * --exclude ChangeLog\* --exclude loaddefs.el --exclude ldefs-boot.el| wc
	330    2245   30068
    [wohler@olgas:589]$ grep -ri tool.bar --exclude \*.elc * --exclude ChangeLog\* --exclude loaddefs.el --exclude ldefs-boot.el| wc
	400    2048   26282

>                                                 But there is no rush
> to change this; let's leave it alone, for now.

Agree, but new code should use "menu bar" and "tool bar."

How about speedbar though?

> Does anyone have any ideas on the issue of how to use the term
> "option"?  That issue is more important--it is not just an issue of
> punctuation, it is inconsistent use of a word.  Would someone like to
> study the situation and find out which uses occur where?

I don't recall this thread. What was the subject?

-- 
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: toolbar conventions

[Richard M. Stallman]

    >                                                 But there is no rush
    > to change this; let's leave it alone, for now.

    Agree, but new code should use "menu bar" and "tool bar."

I agree.  (I do think those are nicer than "menubar" and "toolbar".)

    How about speedbar though?

I think that is always written as one word, as of now.  So let's not
change it.

Re: toolbar conventions

[Bill Wohler]

"Richard M. Stallman" <rms@gnu.org> writes:

>     >                                                 But there is no rush
>     > to change this; let's leave it alone, for now.
>
>     Agree, but new code should use "menu bar" and "tool bar."
>
> I agree.  (I do think those are nicer than "menubar" and "toolbar".)

I had written:

> I can add a Style Guide subheading to (elisp)Coding Conventions and
> (elisp)Documentation Tips and include this information if you like.

Would you like me to do this?

This would also be a good place to place the option usage once that
issue is resolved.

-- 
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: toolbar conventions

[Richard M. Stallman]

    > I can add a Style Guide subheading to (elisp)Coding Conventions and
    > (elisp)Documentation Tips and include this information if you like.

    Would you like me to do this?

It would be useful for you to write a draft and show it to me,
but I am not sure it should be part of the Lisp manual.

Re: toolbar conventions

[Luc Teirlinck]

>From my previous reply:

   I believe that the majority of places in the Emacs code and docs
   still use the word "user option" to mean "user variable".

In particular, Custom buffers, for instance the ones you get from
`customize-browse' still use "Option" in the old sense.

Sincerely,

Luc.

Re: toolbar conventions

[Luc Teirlinck]

Richard Stallman wrote:

   Does anyone have any ideas on the issue of how to use the term
   "option"?  That issue is more important--it is not just an issue of
   punctuation, it is inconsistent use of a word.  Would someone like to
   study the situation and find out which uses occur where?

If we use the name "User Option" for both variables and faces, then
that term would be only useful when discussing the Customize interface
in the Emacs manual.  Apart from the similarity in the way you
customize them through that interface, user variables and faces are
very different.  They even have different name spaces.  (Which makes
talking about "the option foo" meaningless.  This is a nuisance, even
when discussing the Customize interface.)

Calling something a "User Option" in the Elisp manual would be
meaningless, you would have to consistently call them "User Variables".
That means that all uses of defopt in all manuals should be changed to
`@defvr {User Variable}'.  The discussion of defopt in the Texinfo
manual would have to be changed, since the reference to Emacs would no
longer be valid.  This is just one example of all the problems we
would run into and all the work we would have to do to consistently
implement this terminology change.

Sincerely,

Luc.