[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Elisp manual: @section Mode Line Format is unclear
From: |
Alan Mackenzie |
Subject: |
Elisp manual: @section Mode Line Format is unclear |
Date: |
Thu, 29 Dec 2005 23:04:45 +0000 (GMT) |
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)
- Elisp manual: @section Mode Line Format is unclear,
Alan Mackenzie <=