RE: My emacs was upgraded and I am a novice again

["Drew Adams" <drew.adams@oracle.com>]

> > Then, today, when I was changing the face for mode line from *Customize
> > Group: Mode Line Faces*, I saw something like "Display Time Mail Face"
> > which is reported to change the display of "display-time-mail-string"
> > variable. I C-h v'd it, and voila!
>
> I've been (unsuccessfully) looking for this yesterday -- thanks :)
...
> C-h d of "display" gives about 10000 lines of text and this doesn't
> report "display-time-mail-string" as a variable. C-h d of "mail" is
> about 2700 lines of text and this doesn't contain it either. I used
> "mode-line" to search also and I didn't understand anything from
> mode-line-format variable's value, for example. (There is a format
> description with signs like %a, %B, but there is no such thing in the
> value, just a set of cryptic functions without any reference to mail.)
>
> Maybe I gave up early without checking Google, but I used apropos,
> apropos-documentation and describe-variable for the keywords I can
> think of. As you say, there may be too many hits and I might miss (and
> I agree that I'm not a perfect user of documentation), but what I say
> is that this problem is not about documentation format and such
> technicalities; I think it's a result of "information explosion" and
> no perfect communication between user and documentation should be
> expected (as no perfect communication between people exists.) One can
> only provide better tools but this won't solve the problem perfectly.

What you say is true. However, sometimes the information explosion can be
sufficiently tamed that you can find what you need. Tools do sometimes make
a difference.

Icicles command `icicle-doc' lets you search all doc strings (functions,
variables, faces) for matches to one or more doc strings. That's a *lot* of
doc, believe me. For example:

 M-x icicle-doc RET mail S-SPC mode line

shows all doc strings that match both `mail' and `mode line', in any order,
as completion candidates.

Choose a matching candidate to see its full description in buffer *Help*
(with the function signature or variable name and value etc.). You can also
visit each of several (or all) candidates on the fly, using `C-next' (visit
each in turn) or `C-mouse-2' (visit the ones you click).

It is fairly quick this way to find what you were looking for. In spite of
the large volume of doc searched, there are only three matches in vanilla
emacs (-Q): only three functions, variables, or faces whose doc strings
mention both `mail' and `mode line': `display-time', `display-time-mode',
and `rmail-mode'.

Why no `display-time-mail-string'? Because its doc string does not mention
`mail'. That shows the weakness of such an approach: it depends on having
doc that mentions what you're looking for. Nevertheless, using this
approach, you would have very quickly found `display-time' and
`display-time-mode', and from their doc strings you could have gotten to the
appropriate Customize group and found what you needed. It would probably
have taken you less than 5 minutes altogether to find what you were after,
and almost all of that time would have been spent looking over the Customize
group's variables to find that `display-time-mail-string' was pertinent.

No, this is not a panacea. There are several user options in Customize group
`display-time' that involve mail indication in the mode line, and none of
their doc strings mention "mode line" (too bad). The group's doc string does
mention it, but the individual options in the group do not. When this is the
case, `icicle-doc' will not get you where you want to go directly, but it
can still help get you close.

There are also three similar commands, `icicle-fundoc', `icicle-vardoc', and
`icicle-plist', for only functions, only variables, and only property lists,
respectively. They let you match against either or both the
function/variable name and its doc string or the symbol name and its
property list keys and values. This is important because sometimes the name
itself carries information that the doc string does not. In particular, a
function, variable, or symbol name often indicates the operation or type of
object acted upon, and that can cut down considerably on what doc is
searched.

http://www.emacswiki.org/cgi-bin/wiki/Icicles_-_Multi-Completions

There are also Icicles versions of the standard `apropos' commands, which
let you access the list of matches as completion candidates:

http://www.emacswiki.org/cgi-bin/wiki/Icicles_-_Help_on_Candidates#OtherApro
posCommands