bug#12686: PATCH: ambiguous help doc strings

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

> > But if this is not done right away, why not at least do as
> > I suggested in the meantime: move the var-or-fn clause
> > first, so that if a symbol is both it gets treated as both.
> >
> > And that would seem to be appropriate anyway, even if you
> > also do as you suggest, to accommodate other symbols that do
> > not correspond to a minor-mode but which have both var and
> > fun definitions.  IOW, minor modes are not the only case
> > to consider, even if they are an important case.
> 
> If the docstring explicitly refers to the function, I see no 
> reason why Emacs should show both the function and the var.

1. What doc string ("the docstring")?  The fn has a doc string and so does the
var.

Perhaps you are talking about a (probably minority) case where one doc string
explicitly refers to the other, e.g., a fn doc string mentions the var or vice
versa, using a keyword (e.g. `variable').  If so, then yes, in that case there
is no _need_ to show both together, and it would be fine not to.

If you have an easy way of distinguishing that case, fine, it can be excluded.
If you have no easy way, do you really want to scan the string to see if it
mentions the same symbol preceded by a different keyword (e.g. `variable' or
`option', for a fun doc string)?


2. But even if you do not bother to exclude that case, and you show both doc
strings systematically, it's not a big deal.  Typically, one or the other
(usually the var) doc string is quite short.

For example, the minor-mode varible `icicle-mode' has only this (boilerplate) as
its doc (whereas the minor-mode function `icicle-mode' has a _long_ doc string):

  icicle-mode is a variable defined in `icicles-mode.el'.
  Its value is t
  Original value was nil

  Documentation:
  Non-nil if Icicle mode is enabled.
  See the command `icicle-mode' for a description of this minor mode.
  Setting this variable directly does not take effect;
  either customize it (see the info node `Easy Customization')
  or call the function `icicle-mode'.

 You can customize this variable.

And I think things are similar for most cases that are not minor modes.


3. If you really want to think about improving *Help* in a general way then I'd
suggest that the problem is not (within reason) the amount of info we provide
but inadequate organization of it.

For `C-h m' we have tried to impose at least some organization, but essentially
that amounts to only (a) a header line of links to (b) sequentially listed
"sections" that are Emacs pages.  Kind of like a 1990s FAQ web page with an
index/TOC at the top followed by all of the FAQs.

Those header links for `C-h m' are ugly (bold should be banned from Emacs
defaults, because it just doesn't work well for lots of faces), but they are
better than nothing.

Better might be a tabbed organization of the info.  For a symbol such as
`icicle-mode' there could be tabs for the command and the option, for example.
For `C-h m' there could be a major-mode tab and a tab for each minor mode.  Or
some such.

And there are other ways to organize info, besides tabs.

The point here really is that rather than getting excited about finding ways to
exclude some information we should start by including as much as might be
pertinent (fn, var, face,...) and then work on designing a better organized UI.