Re: Undocumented hyperlinks in doc strings.

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

Richard Stallman wrote:

	 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.

   Thanks for noticing and fixing this bug.  Please install your change.

   Meanwhile, it might be another bug to allow more than one whitespace
   character between words like `function' and the function name.
   Multiple spaces never happen in normal text, only when there is
   a sort of deliberate paragraph breaking or tabular structure.
   In those cases, going across paragraphs or fields would probably
   be a mistake.

and:

   Three or more semicolons are the convention for comments that should
   start at the margin, and that is our standard way of commenting out
   code.  Like anything, it could be changed, but that is a rather
   heavy change to make and I would hesitate to do it on account of
   outline-minor-mode.

That leaves two questions to be addressed before I install my change.

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.  _As long as_
the author is careful to check his documentation strings with a C-h v
or C-h f (I always do, but I do not know about other people) that
would be an advantage, because the lack of hyperlink would immediately
point out the problem.

In as far as the second goes, I infer from your response that you
prefer the three semi-colon solution of my original patch over the two
semi-colon re-indentation I proposed in a reply to Stefan.  (I do not
believe that the _current_ two semi-colon indentation makes sense,
since it is "C-M-q instable".)

Just in case, what about a convention to follow ;;; by a single space
if one wants the line two be considered a "heading line" by
outline-minor-mode and by at least two spaces if one wants it to be
considered a "body line".  The three semi-colons are mostly important
for commented out code _inside_ a function and apart from an initial
comment (;;; this used: , in the code at issue) and possibly commented
out parts of the documentation string, at least two spaces usually
follow the semi-colons anyway.  So, in the code in question, one just
would have to replace:

;;; this used:

with:

;;;  this used:

without any other change to the original three semi-colon solution.

With:

";;;;* [^ \t\n]\\|(" instead of the current ";;;;* \\|(" as
outline-regexp in emacs-lisp-mode, none of the commented out code
would be considered a heading line by outline-minor-mode.

Sincerely,

Luc.