Re: (doc) bug for menu-bar-mode

[Chris F.A. Johnson]

On Sun, 9 Dec 2001, Eli Zaretskii wrote:

>
> On 8 Dec 2001, Allan Gottlieb wrote:
>
> > The doc for menu-bar-mode
> >
> >     menu-bar-mode is an interactive compiled Lisp function in `menu-bar'.
> >     (menu-bar-mode FLAG)
> >
> >     Toggle display of a menu bar on each frame.
> >     This command applies to all frames that exist and frames to be
> >     created in the future.
> >     With a numeric argument, if the argument is positive,
> >     turn on menu bars; otherwise, turn off menu bars.
> >
> > suggests that (menu-bar-mode) is a toggle, i.e. that FLAG is
> > optional.
>
> I don't see where the doc string suggests that the FLAG argument is
> optional.  Could you please point out what confused you into thinking
> that?

It's implied in two places:

        1. Toggle refers to changing the state, in which case
           there is no need for an argument.
        2. "With a numeric argument", particularly after using the word
           "toggle", implies that it can be used either with a non-numeric
           argument, or without an argument.

Also, the behaviour when called with 'M-x menu-bar-mode' is that of a
toggle, and it takes no argument.

The doc string should make it clear that, when used interactively, it is a
toggle which takes no argument; when evaluated as a lisp expression, it
requires a numeric argument.

-- 
        Chris F.A. Johnson                              bq933@torfree.net
        =================================================================
        c.f.a.johnson@rogers.com                http://cfaj.freeshell.org
        cfaj@freeshell.org        http://members.rogers.com/c.f.a.johnson