Re: Undocumented hyperlinks in doc strings.

[Luc Teirlinck]

Richard Stallman wrote:

   Perhaps it would be a good idea not to make a hyperlink to a face
   name unless the word "face" precedes or follows the face name.
   Would you like to implement that change?

What about the diff below?  It also changes `help-xref-symbol-regexp',
because that variable is used with emacs-lisp-mode-syntax-table,
meaning that newlines do not count as whitespace.  As a consequence,
preceding a variable, function or face by `symbol', `variable' and the
like has no effect if the word is separated from the symbol by a
newline.  This means that a simple M-q can easily enable or disable
several hyperlinks.  This does not seem good.  The change in
`help-xref-symbol-regexp' treats newlines as any other whitespace.
The exact specs for face hyperlinks would be:
preceded by "face" or followed by whitespace (including newline),
"face" and then a non word constituent character.

The diff below also makes the comments in `help-make-xrefs' more in
line with (elisp)Comment Tips.  Most of this was done for me by C-M-q,
but I made the double semicolons in the commented out code into
triple semicolons myself, because that is how (elisp)Comment Tips
wants code commented out.

If you agree with the diff below, I could commit it and adjust the
documentation in several places of the Elisp manual, documentation
strings and the NEWS accordingly.


===File ~/help-mode-diff====================================
cd ~/emacscvsdir/emacs/lisp/
diff -c /home/teirllm/help-mode.old.el 
/home/teirllm/emacscvsdir/emacs/lisp/help-mode.el
*** /home/teirllm/help-mode.old.el      Tue Sep  2 07:33:28 2003
--- /home/teirllm/emacscvsdir/emacs/lisp/help-mode.el   Thu Oct  9 21:17:17 2003
***************
*** 213,219 ****
                    "\\(function\\|command\\)\\|"
                    "\\(face\\)\\|"
                    "\\(symbol\\)\\|"
!                   "\\(source \\(?:code \\)?\\(?:of\\|for\\)\\)\\)\\s-+\\)?"
                    ;; Note starting with word-syntax character:
                    "`\\(\\sw\\(\\sw\\|\\s_\\)+\\)'"))
    "Regexp matching doc string references to symbols.
--- 213,220 ----
                    "\\(function\\|command\\)\\|"
                    "\\(face\\)\\|"
                    "\\(symbol\\)\\|"
!                   "\\(source \\(?:code \\)?\\(?:of\\|for\\)\\)\\)"
!                   "[ \t\n]+\\)?"
                    ;; Note starting with word-syntax character:
                    "`\\(\\sw\\(\\sw\\|\\s_\\)+\\)'"))
    "Regexp matching doc string references to symbols.
***************
*** 342,352 ****
                           (sym (intern-soft data)))
                      (if sym
                          (cond
!                          ((match-string 3) ; `variable' &c
                            (and (boundp sym) ; `variable' doesn't ensure
                                          ; it's actually bound
                                 (help-xref-button 8 'help-variable sym)))
!                          ((match-string 4) ; `function' &c
                            (and (fboundp sym) ; similarly
                                 (help-xref-button 8 'help-function sym)))
                         ((match-string 5) ; `face'
--- 343,353 ----
                           (sym (intern-soft data)))
                      (if sym
                          (cond
!                          ((match-string 3)  ; `variable' &c
                            (and (boundp sym) ; `variable' doesn't ensure
                                          ; it's actually bound
                                 (help-xref-button 8 'help-variable sym)))
!                          ((match-string 4)   ; `function' &c
                            (and (fboundp sym) ; similarly
                                 (help-xref-button 8 'help-function sym)))
                         ((match-string 5) ; `face'
***************
*** 354,365 ****
                               (help-xref-button 8 'help-face sym)))
                           ((match-string 6)) ; nothing for `symbol'
                         ((match-string 7)
! ;; this used:
! ;;                       #'(lambda (arg)
! ;;                           (let ((location
! ;;                                  (find-function-noselect arg)))
! ;;                             (pop-to-buffer (car location))
! ;;                             (goto-char (cdr location))))
                          (help-xref-button 8 'help-function-def sym))
                           ((and (boundp sym) (fboundp sym))
                            ;; We can't intuit whether to use the
--- 355,366 ----
                               (help-xref-button 8 'help-face sym)))
                           ((match-string 6)) ; nothing for `symbol'
                         ((match-string 7)
! ;;; this used:
! ;;;                     #'(lambda (arg)
! ;;;                         (let ((location
! ;;;                                (find-function-noselect arg)))
! ;;;                           (pop-to-buffer (car location))
! ;;;                           (goto-char (cdr location))))
                          (help-xref-button 8 'help-function-def sym))
                           ((and (boundp sym) (fboundp sym))
                            ;; We can't intuit whether to use the
***************
*** 370,376 ****
                         ((fboundp sym)
                          (help-xref-button 8 'help-function sym))
                         ((facep sym)
!                         (help-xref-button 8 'help-face sym)))))))
                ;; An obvious case of a key substitution:
                (save-excursion
                  (while (re-search-forward
--- 371,378 ----
                         ((fboundp sym)
                          (help-xref-button 8 'help-function sym))
                         ((facep sym)
!                         (if (save-match-data (looking-at "[ \t\n]*face\\W"))
!                             (help-xref-button 8 'help-face sym))))))))
                ;; An obvious case of a key substitution:
                (save-excursion
                  (while (re-search-forward

Diff finished at Thu Oct  9 21:26:20
============================================================