RE: [drew.adams@oracle.com: links in Help buffer aren't alwayscorrect]

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

    > The text "buffer-list" in the last sentence is linked to the
    > help for the `buffer-list' function, not the `buffer-list' frame
    > parameter. Either there should be no link here (if there is no
    > way to show help on the parameter) or
    > the link should point to help on the frame parameter.

    Since there is no describe-frame-parameter command, and the phrase
    "frame paramter" follows the quoted symbol (unlike the phrases listed
    in help-xref-symbol-regexp, which precede quoted symbols), we can avoid
    hyperlinking such phrases by changing help-make-xrefs in help-mode.el
    from:

                   ;; Quoted symbols
                   (save-excursion
                     (while (re-search-forward
    help-xref-symbol-regexp nil t)
                       (let* ((data (match-string 8))
                              (sym (intern-soft data)))
                         (if sym

    to:

                   ;; Quoted symbols
                   (save-excursion
                     (while (re-search-forward
    help-xref-symbol-regexp nil t)
                       (let* ((data (match-string 8))
                              (sym (intern-soft data)))
                         (if (and sym
                                  (save-match-data
                                    (not (looking-at "[ \t\n]+frame
    parameter"))))

I agree with the intention, but have doubts about the implementation - it
seems fragile, depending as it does on the exact text in the doc string. If
someone writes "frame parameter `buffer-list'" instead of "the `buffer-list'
frame parameter" then it won't work correctly. Likewise, if someone writes a
French doc string for a function or var that refers to a frame parameter.

But I guess the same could be said for the use of `help-xref-symbol-regexp',
generally. Given that we do use `help-xref-symbol-regexp' in a way that
depends on the exact doc-string text, wouldn't it be better to add the
doc-string convention to always precede the specific name by the type, so,
for instance, this doc string would say "frame parameter `buffer-list'"?
Then, "frame parameter could be added to `help-xref-symbol-regexp'.

There may not be a `describe-frame-parameter' function, but the
`help-make-xrefs' code could use a preceding "frame parameter" to link to
the Info section describing the `buffer-list' parameter. Or, at the very
least, it could test for preceding "frame parameter" in order to do nothing
(add no link) if it is present.