Subject: bug#30397: Random numbers in grep mode-line

From: Drew Adams <[email-masked]>
Date: Fri, 9 Feb 2018 07:59:12 -0800 (PST)

> > If you agree that better help about this would be
> > in order, where would you suggest putting that help,
> > if not on `C-h m'?
> 
> Our current practice is to describe that in the manual.

That's OK by me.  Somewhere is better than nowhere.  The
manual is better than just NEWS.

> If we decide to add that to "C-h m", we should do that
> for all the modes.

That doesn't follow.

We sometimes describe some keys in `C-h m' output.  That
doesn't mean we should describe all keys in the mode map.

We should describe what needs to be described - in
particular, (1) things that might be the least obvious,
clear or easy to discover and (2) things that might be
the most important to know.

> We should also consider the discoverability:

Definitely.  That's why NEWS doesn't suffice.

The best discoverability for something in the mode-line
is mouseover tooltip info - right there.  The second best
is clicking that thing in the mode line - right there.

For mode indications in the mode-line, I do think that
`C-h m' would not be a bad place to describe them, when
the info is needed (i.e., when they are not clear on
their own and you cannot get more info about them from
the mode-line itself - see previous).

> "C-h m" is not where I would look for documentation
> of a mode, only for its keybindings.

Only its key bindings?  Not I.  To me, `C-h m' should
give an overview of the mode: what it's for etc.  If
`C-h m' for some mode just lists a few key bindings
then I'm disappointed and want more info.

`C-h m' is sometimes (often? typically?) the doc
string of the mode function.  As such, like any
command doc string, it should describe the command.

I mention these general thoughts about `C-h m' because
you brought up the general question.  I have no problem
with this bug being fixed by adding description in the
manual.  And perhaps modifiying what users see for
`grep' in the UI.