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)