bug#9445: 24.0.50; `help-make-xrefs' has bad logic

[Drew Adams]

1. The doc string is inaccurate and misleading.  It says:
 
"Faces only get cross-referenced if
preceded or followed by the word `face'.
 
What really seems to happen is that if preceded by the word `face' then
ONLY a face is looked for to cross-reference.  That is not at all the
same thing.
 
It also says:
 
"Variables without
variable documentation do not get cross-referenced, unless
preceded by the word `variable' or `option'."
 
Again, what really seems to happen is that if preceded by one of those
words then ONLY a variable or option, resp., is looked for to
cross-reference.  Not at all the same thing.
 

2. Besides the doc describing the behavior incorrectly, the behavior itself is
broken/poor.  What SHOULD happen, if you must key off of
the preceding word, is that the type of thing guessed at due to that
preceding word is looked for FIRST, but not EXCLUSIVELY.

You simply look for `variable', and if you find it then you check for a
documented variable of that name.  That's silly - not enough.
 
E.g., if a function name `foo' happens to be preceded by `face',
`variable', or `option', and if there is no corresponding foo `face',
`variable', or `option', then it SHOULD pick up and cross-reference
the FUNCTION `foo'.

In sum, try your heuristics in order until you find a match or there is no
match.  Do not just try one and then give up.
 
If you introduce a sketchy heuristic such as using the preceding word,
then at least follow through and DTRT if no xref of that corresponding
type can be found.  Do not just ASSUME that the preceding word is the
be-all and end-all, necessarily determining perfectly the proper type.
It's just a FIRST GUESS.  If it doesn't match, then DTRT - look for a
function, command, etc.


FWIW, it took me a while to figure out why, in a list of command names and their
descriptions, there was an occasional command name that had no link.  It turned
out that the preceding line (the end of the previous commands' one-liner
description) ended with "face" or "option" etc.  Sheesh.
 

In GNU Emacs 24.0.50.1 (i386-mingw-nt5.1.2600)
 of 2011-08-29 on 3249CTO
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (4.5) --no-opt'