Re: Undocumented hyperlinks in doc strings.

[Luc Teirlinck <teirllm@dms.auburn.edu>]

Richard Stallman wrote:

       In as far as the first one goes, one could replace the occurrences of
       [ \t\n]+ and [ \t\n]* (the latter probably would have to be changed to
       [ \t\n]+ anyway, for consistency) in my patch by [ \n].  (If one does
       not allow multiple spaces, it seems consistent not to allow tab
       either.)  That would mean that the author would have to be careful
       about "space related sloppiness" like trailing whitespace or an
       inadvertent inappropriate double space inside a sentence.

   That is true.  I am not sure which approach would actually do a better job
   in practice.

I would be leaning toward keeping [ \t\n]+, although this is a close
call and I am not really sure either.

There is some more strange behavior in connection with these
hyperlinks.  Evaluate

(defvar sillyvar nil
  "Documents the strange behavior of `button'.
Also, the symbol `tool-bar-mode' and dynamic `use-mouse-action'.")

and do C-h v sillyvar.  Then in the *Help* buffer click with mouse-2 on
`button'.

The behavior in the next paragraph seems deliberate.  I just describe
it in detail, in case it would not be.

In spite of my patch, we now see the face documentation of `button'.
That is because, in the absence of a hyperlink, mouse-2 is bound to
`help-follow-mouse' which will follow and list all available
documentation regardless of any convention.  `help-make-xrefs' is not
involved here.  Mouse-2 also will follow `tool-bar-mode' in spite of
the `symbol' in front of it.  (The `symbol' prevents the making of a
hyperlink for the following symbol, but does not actually prevent
mouse-2 from listing all available documentation for that symbol.)
Mouse-2 will also follow the following `and', viewing it as the lisp
special form.

All the above is probably deliberate, but now things get more
"exotic".  In the face documentation of `button' click on [back].  Of
course, we get the doc string of sillyvar back, but it has changed.
Previously, `button' and `use-mouse-action' were not underlined,
because they were not hyperlinks, but now they are underlined.  One
can check that neither `button' not `use-mouse-action' are defined as
variables, before clicking once more on `button' with mouse-2 and
getting:

button's value is 
#<marker
(moves after insertion)
at 20 in *Help*>

Not documented as a variable.

[back]

What happens is that button is not defined as a global variable.
However, when clicking on a hyperlink, mouse-2 is bound to
`push-button', whose code contains:

    (let ((button (button-at (or pos (point)))))
      (if (not button)
        nil
	(button-activate button use-mouse-action)
	t))))

`button' and `use-mouse-action' now are dynamically bound.  When we
clicked on `back' in the face documentation `button' and
`use-mouse-action' were dynamically `boundp' when `help-make-xrefs'
was deciding whether a hyperlink should be made for them.  In the
*Help* buffer they were not boundp any more, but once we actually
clicked on the hyperlink, `button' was boundp again, and its dynamic
binding got displayed.

`button' being a text property, we can not just avoid to use it in
documentation strings.  What about replacing:

                      ((boundp sym)
	               (help-xref-button 8 'help-variable sym))

by:

                      ((and (boundp sym)
                            (not (string= sym "button")))
		       (help-xref-button 8 'help-variable sym))

That would still make a hyperlink for: the variable `button' 
but not for a mere: `button'.

`button' appears to be the only real problem.  I do not believe that
`use-mouse-action' is likely to actually occur in hyperlinks.  Hence,
it might not be worth worrying about.

Out of curiosity one can click on the `use-mouse-action' hyperlink
anyway and get:

use-mouse-action's value is t

Not documented as a variable.

[back]

Sincerely,

Luc.