Elisp manual: @section Mode Line Format is unclear

Elisp manual: @section Mode Line Format is unclear

[Alan Mackenzie]

Hi, Emacs!

Emacs 22.

I find the documentation of the Mode Line very unclear.  I'm confident
that all the information is there; it's just that it takes a very great
deal of effort to extract the useful nuggets of information.

Why do I say this?  The writing is excessively abstract:  For example, we
have (on page "The Data Structure Of the Mode Line") this:

 - Variable: mode-line-format
     The value of this variable is a mode-line construct with overall
     responsibility for the mode-line format.  The value of this
     variable controls which other variables are used to form the
     mode-line text, and where they appear.

This helps me not at all when I want to know how to put the string "/la"
next to the major mode name.  Carrying on, we get:

       A mode-line construct may be as simple as a fixed string of text, but
    it usually specifies how to use other variables to construct the text.
    Many of these variables are themselves defined to have mode-line
    constructs as their values.

What the hello there is a "mode line construct"?  Why should I have to
bother figuring this out?  (It's not explained anywhere on this page,
despite there being a "@dfn{mode line construct}" - This @dfn is purely
recursive, defining the term as something built up from mode line
constructs.)  Next on the agenda is:

       The default value of `mode-line-format' incorporates the values of
    variables such as `mode-line-position' and `mode-line-modes' (which in
    turn incorporates the values of the variables `mode-name' and
    `minor-mode-alist').  Because of this, very few modes need to alter
    `mode-line-format' itself.  For most purposes, it is sufficient to
    alter some of the variables that `mode-line-format' either directly or
    indirectly refers to.

This is beginning to get patronising - "Don't worry your pretty little
head about all this complicated stuff.  All _you_ need to do is change a
few variables.  You probably wouldn't understand the difficult bits
anyway.".  Next:

       A mode-line construct may be a list, a symbol, or a string.  If the
    value is a list, each element may be a list, a symbol, or a string.

This is VERY patronising:  it says nothing more than "A mode-line
construct is an Emacs lisp object".  Well, who'd've thought it?  At this
point, I'm beginning to get angry.  How much more of this woffle do I
need to plough through before it actually tells me how to put the string
"/la" next to the major mode name?

A bit lower down we've got A PASSIVE VOICE SENTENCE!!!!!!  An ugly,
nasty, passive voice sentence:

    `STRING'
         A string as a mode-line construct is displayed verbatim in the
         mode line except for "`%'-constructs".  Decimal digits after the
         `%' specify the field width for space filling on the right (i.e.,
         the data is left justified).  *Note %-Constructs::.

This is beginning to give me some detail.  It's half-telling me _what_ I
can do with a "mode-line construct" (but what the fuchsia is a "percent
construct"?), but it still, maddeningly, gives me no clue HOW to go about
doing this.  Why isn't there something like: "For example, you could
write ??????? to put .......... onto the mode line"?

FINALLY, we get to an example at the bottom.  Then I've got to go through
the tedium of parsing this example into distint "mode-line constructs"
(which still haven't been explained), then jumping back and forth to the
list above, and searching for a matching entry.

"Specifiers", anybody?  ;-(

Surely, we can do better than this.

-- 
Alan Mackenzie (Munich, Germany)

Re: Elisp manual: @section Mode Line Format is unclear

[Andreas Schwab]

Alan Mackenzie <acm@muc.de> writes:

>        A mode-line construct may be as simple as a fixed string of text, but
>     it usually specifies how to use other variables to construct the text.
>     Many of these variables are themselves defined to have mode-line
>     constructs as their values.
>
> What the hello there is a "mode line construct"?  Why should I have to
> bother figuring this out?  (It's not explained anywhere on this page,
> despite there being a "@dfn{mode line construct}" - This @dfn is purely
> recursive, defining the term as something built up from mode line
> constructs.)

A mode-line construct is a recursive entity.  The precise list of forms
follows.  What is that if not a definition?

>        A mode-line construct may be a list, a symbol, or a string.  If the
>     value is a list, each element may be a list, a symbol, or a string.
>
> This is VERY patronising:  it says nothing more than "A mode-line
> construct is an Emacs lisp object".

Because it is, like a lisp object, a recursive entity.

> A bit lower down we've got A PASSIVE VOICE SENTENCE!!!!!!  An ugly,
> nasty, passive voice sentence:
>
>     `STRING'
>          A string as a mode-line construct is displayed verbatim in the
>          mode line except for "`%'-constructs".  Decimal digits after the
>          `%' specify the field width for space filling on the right (i.e.,
>          the data is left justified).  *Note %-Constructs::.
>
> This is beginning to give me some detail.  It's half-telling me _what_ I
> can do with a "mode-line construct" (but what the fuchsia is a "percent
> construct"?)

Care to follow the cross reference?

> FINALLY, we get to an example at the bottom.  Then I've got to go through
> the tedium of parsing this example into distint "mode-line constructs"
> (which still haven't been explained)

See above.

> "Specifiers", anybody?  ;-(

??? Where do you see "specifiers"?

Andreas.

-- 
Andreas Schwab, SuSE Labs, schwab@suse.de
SuSE Linux Products GmbH, Maxfeldstraße 5, 90409 Nürnberg, Germany
PGP key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: Elisp manual: @section Mode Line Format is unclear

[David Kastrup]

Andreas Schwab <schwab@suse.de> writes:

> Alan Mackenzie <acm@muc.de> writes:
>
>> "Specifiers", anybody?  ;-(
>
> ??? Where do you see "specifiers"?

I think he is referring to a particular set of rants I made on XEmacs
developer lists when getting exasperated about circularity and a lack
of comprehendability in XEmacs-specific parts of the Lisp
documentation.  The resulting outfalls made for a significant part of
my popularity there.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Elisp manual: @section Mode Line Format is unclear

[Richard M. Stallman]

I made some changes.
Is it clearer now?

Re: Elisp manual: @section Mode Line Format is unclear

[Stephen J. Turnbull]

>>>>> "Andreas" == Andreas Schwab <schwab@suse.de> writes:

    Andreas> What is that if not a definition?

It *is* a definition.  What it is not, is *documentation*.  Thus the
reference to "specifiers" (an over-elaborated XEmacs API full of YAGNI[1]
violations, whose documentation focuses on what YAGN).

What Alan would like to see, I suppose, is something like:

 - Variable: mode-line-format
     The value of this variable is a mode-line construct which
     describes the mode-line to redisplay.

     The simplest form of mode-line construct is a string containing
     zero or more %-constructs.  A %-construct is a reference to a
     variable whose value is to be interpolated into the modeline at
     that point.  The %-construct is introduced by the character `%',
     followed by optional formatting specifications, and terminated by
     a single character which indicates the variable whose value is to
     be interpolated.

     Example: `(setq mode-line-format "%B")' puts the buffer name, and
     nothing else, in the mode-line of the current buffer.

     A symbol is also a modeline construct.  Its value is interpolated
     in the 


Footnotes: 
[1]  "You Aren't Gonna Need It", for those who most naturally
interpret "XP" to refer to a proprietary operating system, is one of
the basic ideas of the XP == Extreme Programming style.

-- 
School of Systems and Information Engineering http://turnbull.sk.tsukuba.ac.jp
University of Tsukuba                    Tennodai 1-1-1 Tsukuba 305-8573 JAPAN
               Ask not how you can "do" free software business;
              ask what your business can "do for" free software.

Re: Elisp manual: @section Mode Line Format is unclear (cont.)

[Stephen J. Turnbull]

Sorry about the premature send.  I just got in from playing with my
daughter and my frozen fingers weren't flexible enough to get to C-x C-x....

Prefatory material omitted, here's the beef.

What Alan would like to see, I suppose, is something like:

 - Variable: mode-line-format
     The value of this variable is a mode-line construct which
     describes the mode-line to redisplay.

     The simplest form of mode-line construct is a string containing
     zero or more %-constructs.  A %-construct is a reference to a
     variable whose value is to be interpolated into the modeline at
     that point.  The %-construct is introduced by the character `%',
     followed by optional formatting specifications, and terminated by
     a single character which indicates the variable whose value is to
     be interpolated.  *Note:: %-constructs.  Example:

     `(setq mode-line-format "%B")'

     puts the buffer name, and nothing else, in the mode-line of the
     current buffer.

     A symbol is also a mode-line construct.  Its value is interpolated
     in the mode-line display, but %-constructs are *not* interpreted.
     Example:

     `(setq buffer-format "%B" mode-line-format 'buffer-format)'

     does not have the same effect as the above.  Instead, it produces
     a (rather useless) mode-line containing only the string "%B".

     The mode-line can include images by [however you do that in Emacs].

     Finally, a mode-line construct may be a list of mode-line
     constructs.  If the car is a symbol, the list is treated as a
     conditional.  If the symbol's value is non-nil, the cadr is
     evaluated (recursively, as necessary), and interpolated.
     Otherwise the caddr is evaluated and interpolated.

     If the car is an integer, its magnitude is a target width.  When
     positive, the rest of the elements of the list are evaluated,
     concatenated, and if necessary right-padded with spaces to
     achieve the target width.  When negative, the result is truncated
     to the target width.

     Otherwise, these are evaluated (recursively, as necessary) until
     all resolve to strings, which are concatenated left-to-right to
     produce the mode-line display.  Example:

     `(setq buffer-format "%B" mode-line-format '("%B" buffer-format))'

     displays a mode-line containing the buffer name, followed by the
     string "%B" with no space intervening.

(Note: the above is not likely to be an accurate description of either
XEmacs or Emacs, as there are other, more arcane possibilities.)


-- 
School of Systems and Information Engineering http://turnbull.sk.tsukuba.ac.jp
University of Tsukuba                    Tennodai 1-1-1 Tsukuba 305-8573 JAPAN
               Ask not how you can "do" free software business;
              ask what your business can "do for" free software.