Re: Undocumented hyperlinks in doc strings.

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

Stefan Monnier wrote:

   It's a fundamental problem that the convention leads to ambiguities
   that only a human being can resolve.

That could be mended by a slight change in the current standard
(which, to me, means: "as recommended in the Elisp manual") way of
commenting out code, which I proposed in an earlier message: follow
the semicolons by a single space if the line is meant to be a heading
line and by at least two spaces otherwise.  Anyway, in as far as I am
concerned, one could stay with the current standard as is, or add my
proposed modification, or change to your proposed convention, I do not
mind either way, as long as the actual chosen standard is accurately
and clearly documented in the Elisp manual.

I want to concentrate on the commented out code in `help-make-xrefs'
which according to me is should simply be deleted:

                         ((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))

The "commented out code" is actually not code "commented out in
place", but the old second argument to `help-xref-button', which, at
the time, also required an extra fourth argument.  This got replaced
in revision 1.232 to help.el by the current second argument
'help-function-def.  I believe the "commented out code" has been
obsolete for more than two years by now.  Why keep it?  If we
systematically kept old code around like this and never deleted it,
source files would quickly become bloated and hard to read.

Sincerely,

Luc.