GNU bug report logs - #12686
PATCH: ambiguous help doc strings

Previous Next

Full log

Message #17 received at 12686 <at> debbugs.gnu.org (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Stefan Monnier'" <monnier <at> iro.umontreal.ca>,
	"'Juri Linkov'" <juri <at> jurta.org>
Cc: 12686 <at> debbugs.gnu.org, "'Aaron S. Hawley'" <aaron.s.hawley <at> gmail.com>
Subject: RE: bug#12686: PATCH: ambiguous help doc strings
Date: Tue, 23 Oct 2012 09:15:05 -0700

> 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').

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.