Re: Undocumented hyperlinks in doc strings.

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

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
============================================================