Re: Mode line documentation in Emacs manual fails.

[Eli Zaretskii]

> Date: Mon, 8 Dec 2008 12:49:54 +0000
> From: Alan Mackenzie <address@hidden>
> 
> Hi, Emacs!
> 
> Sorry to be so negative, but I see this on a mode line on a text-only
> terminal:
> 
>     -111:---F4  31n/diff-bug-dir.sh   All L7    C0    
> (Shell-script[bash])----P202/810
> 
> What does the "-111:-" bit mean?  OK, I could certainly work it out from
> the manual, but this working out is arduous indeed.  On manual page
> "Mode Line":
> 
>    CS describes the character set of the buffer (see Coding
>    Systems).  If it is a dash (`-'), that indicates the default state of
>    affairs: no special character set handling, except for the end-of-line
>    translations described in the next paragraph.  `=' means no conversion
>    whatsoever.  Letters represent various nontrivial "coding systems"--for
>    example, `1' represents ISO Latin-1.  On a text-only terminal, CS is
>    preceded by two additional characters that describe the coding system
>    for keyboard input and the coding system for terminal output.
>    Furthermore, if you are using an input method, CS is preceded by a
>    string that identifies the input method, which takes the form `I>',
>    `I+', or `I@' (see Input Methods).
> 
> "`1' represents ISO Latin-1".  Is this the left `1', the middle `1', or
> the right `1'?

All of them, of course, since the ones are identical.

But this sentence talks about the rightmost one, of course (unless you
are willing to argue that ``preceded by'' is ambiguous because no one
said the text has left to right direction ;-).

> "On a text-only terminal, CS is preceded by two additional characters
> that describe the coding system for keyboard input and the coding system
> for terminal output".  This is surely wrong.  These two additional
> characters are part of CS, aren't they?

No, CS is a description only of the buffer's character set
(a.k.a. buffer-file-coding-system), and the manual spells that
correctly.

> I think my greatest difficulty is picking out the CS field from the rest
> of the mode line.  The text is confused as to whether the ":" is part of
> the CS field or not.  "If it is a dash (`-') ...." is very squidgy,
> because the field is (?sometimes?) preceded by a dash.  Why is the
> default "-" character the same as the content-free leader character?

Because `-' is a gap-filling character, used where we have nothing
special to say.

> "The CS string and the colon character after it describe the character
> set .....".  How does the colon character aid in this description?

It describes the EOL format, which is traditionally viewed as part of
the encoding (not just by Emacs).

> I think there's too much woffle in this section, e.g. "Normally, Emacs
> handles these settings intelligently, but it is sometimes useful to have
> this information" doesn't seem to say anything much.

It explains why we put such obscure information in the user manual.
Patches to improve this part of the manual are more than welcome.

By the way, is there something specific in this section that is
unclear?  If so, please tell what that is.