bug#24842: 24.5; `help-make-xrefs': False link-type determinations

[Drew Adams]

`help-make-xrefs' tries to guess the type of a symbol that is enclosed
in `...', in help.

This determination needs to to be improved, or else programmers need
some way to inhibit it when it turns out to be inappropriate.

Example: This is part of a doc string I have:

`isearchp-movement-unit-alist'\t- units and their movement functions
`isearchp-on-demand-action-function'\t- on-demand action function
`isearchp-prompt-for-filter-name'\t- when to ask for filter name

Those symbols are all variables (in fact, user options), not functions.
but the word "function" at the end of the second line causes the quoted
symbol that follows it to be considered as a function name.  And then,
because it is not `fboundp', it gets no link.  It should instead get a
variable-name link to its definition.

1. One possible approach is to improve the behavior.  I have not tested
   this generally, but changing the `cond' clauses to include the test
   for type and for documentation as part of the `cond' test, instead of
   being part of the result clause after the test, fixes at least the
   immediate problem of the above example.

   For example, instead of:

   ((match-string 4)   ; `function' &c
    (and (fboundp sym) ; similarly
         (help-xref-button 8 'help-function sym)))

   use this:

   ((and (match-string 4) ; `function' &c
         (fboundp sym))   ; similarly
    (help-xref-button 8 'help-function sym))

   Similarly for the other clauses.

   Possibly this does not DTRT generally, since it lets subsequent
   `cond' clauses get tested if the code cannot determine that the
   symbol is a variable, function, etc.

   But that's the point of those clauses.  If they cannot find that some
   symbol is a variable, etc., then shouldn't the subsequent clauses be
   tried?  (The tests might need to be improved.  Dunno.)

   Again, I have not tested this, so I don't propose an exact code fix.
   I'm reporting the bug.

2. An alternative, if you don't find that #1 is reasonable, could be to
   explicitly provide for (and document) some way for a programmer to
   "escape" a given quoted symbol from a "determiner" such as "function"
   that immediately precedes it.

   The regexp used now looks for whitespace after the "determiner": any
   combination of space, tab, and newline chars.

   I can insert a NULL char, x00, after "function", and that "fixes"
   things, but that char then appears in the output, as "^@".  Another
   Unicode whitespace char could be used instead, etc.  But that still
   means another character that gets rendered, increasing the line
   length, etc.

   If #2 is chosen, the solution should hopefully be more robust and
   cleaner that such a hack.

I hope you will consider fixing this in some way.


In GNU Emacs 24.5.1 (i686-pc-mingw32)
 of 2015-04-11 on LEG570
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=/c/usr --host=i686-pc-mingw32'