Lisp manual is incomplete w.r.t. mode-line-format

Lisp manual is incomplete w.r.t. mode-line-format

[Kevin Rodgers]

In GNU Emacs 21.3.2 (i386-pc-solaris2.8, X toolkit) of 2003-05-22 on
zeus, the documentation for mode-line-format (in the Emacs Lisp
Reference Manual edition 2.8) is incomplete.

In describing a symbol or a list whose car is a symbol, the doc string
says the symbol's value is used, from which I would infer that the
symbol must be bound.

But the Lisp manual says that a SYMBOL construct whose value is void is
ignored.  That's OK, as that level of detail may not be appropriate for
the doc string.

But the manual does not say anything about an unbound symbol in a
(SYMBOL THEN [ELSE]) construct.  Experiment shows that when SYMBOL is
void the ELSE element is used, rather than ignoring the entire
construct.  Is that the correct behavior?  It should be documented.

The manual also says that "A list whose first element is a symbol that
is not a keyword specifies a conditional".  So how should (:KEYWORD ...)
be interpreted?  Experiment shows that (:foo "bar") is "bar", but (:foo)
is "*invalid*".

Finally, the manual does not explain what the result is when (:eval
FORM) causes an error.  From experiment, it is ignored.

Thanks,
-- 
Kevin Rodgers

Re: Lisp manual is incomplete w.r.t. mode-line-format

[Richard Stallman]

    But the manual does not say anything about an unbound symbol in a
    (SYMBOL THEN [ELSE]) construct.  Experiment shows that when SYMBOL is
    void the ELSE element is used, rather than ignoring the entire
    construct.  Is that the correct behavior?  It should be documented.

Could someone verify that this is still true in the current sources?
Then I will document it.

Re: Lisp manual is incomplete w.r.t. mode-line-format

[Kevin Rodgers]

Kevin Rodgers wrote:
> In GNU Emacs 21.3.2 (i386-pc-solaris2.8, X toolkit) of 2003-05-22 on
> zeus, the documentation for mode-line-format (in the Emacs Lisp
> Reference Manual edition 2.8) is incomplete.
...
> Finally, the manual does not explain what the result is when (:eval
> FORM) causes an error.  From experiment, it is ignored.

In Emacs 22, is the error caught by apply-mode-line-format or by the
display engine?

-- 
Kevin Rodgers

Re: Lisp manual is incomplete w.r.t. mode-line-format

[Luc Teirlinck]

Richard Stallman wrote:

       But the manual does not say anything about an unbound symbol in a
       (SYMBOL THEN [ELSE]) construct.  Experiment shows that when SYMBOL is
       void the ELSE element is used, rather than ignoring the entire
       construct.  Is that the correct behavior?  It should be documented.

   Could someone verify that this is still true in the current sources?
   Then I will document it.

It appears to still be true.  But it is not just the Elisp manual that
fails to mention this and should be fixed.  The `mode-line-format'
docstring does not mention it either.  Is it intentional behavior?

Sincerely,

Luc.

Re: Lisp manual is incomplete w.r.t. mode-line-format

[Richard Stallman]

    It appears to still be true.  But it is not just the Elisp manual that
    fails to mention this and should be fixed.  The `mode-line-format'
    docstring does not mention it either.  Is it intentional behavior?

Yes and no.  It has to do SOMETHING in this case, but it must not
signal an error.  So this seems like the best thing for it to do.

Re: Lisp manual is incomplete w.r.t. mode-line-format

[Stefan Monnier]

>     It appears to still be true.  But it is not just the Elisp manual that
>     fails to mention this and should be fixed.  The `mode-line-format'
>     docstring does not mention it either.  Is it intentional behavior?

> Yes and no.  It has to do SOMETHING in this case, but it must not
> signal an error.  So this seems like the best thing for it to do.

Also it's convenient for the typical var which defaults to nil but might not
yet be loaded (i.e. where unbound and nil are somewhat equivalent).
Those same variables which would be tested with bound-and-true-p.

Of course we could also define (VAR THEN-FORMAT ELSE-FORMAT UNBOUND-FORMAT)
so the fourth element is used if the var is unbound instead of being nil.


        Stefan