bug#12686: PATCH: ambiguous help doc strings

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

> BTW, a common cause of ambiguity is minor modes which use the same
> symbol as a function and as a variable.  But in most such 
> cases, I think the fix is not to fix the ambiguity but to make
> describe-function/variable aware of minor-modes and display them in
> a unified way (i.e. display a single *Help* buffer that shows the var
> and the fun as a single entity, e.g. giving the args but also the link
> to customize).

+1, but not necessarily in the describe-function/variable code.  It should be
enough to do it once, in `help-make-xrefs'.

And this is already done, to some extent.  `help-make-xrefs' already DTRT,
**IF** the symbol name is not preceded by a keyword such as `function' or
`variable', i.e., if the match against `help-xref-symbol-regexp' does not match
`match-string' 1 through 7, and the symbol is both a var and a fn with doc.

In that case, we use button type `help-symbol', which DTRT: it shows the help
for both the function and the variable.

For example, if `icicle-mode' appears in the help text without any intro word
such as `function', `variable', or `option', then when you click it you get the
help for both the mode function `icicle-mode' and the mode variable (option)
`icicle-mode'.

`help-make-xrefs' could be tweaked to improve the accuracy in the case of a mode
fn/var (or any other symbol that is both a fn and a var): Just change the `cond'
order clauses, moving this clause before the other clauses:

((and (or (boundp sym)
          (get sym 'variable-documentation))
      (fboundp sym))
 ;; We can't intuit whether to use the
 ;; variable or function doc -- supply both.
 (help-xref-button 8 'help-symbol sym))

I.e., instead of providing such all-of-the-above behavior only as a fallback,
provide it anytime we know that a given symbol is both a fn and a var (by using
button type `help-symbol').