Re: Undocumented hyperlinks in doc strings.

[Luc Teirlinck]

Stefam Monnier wrote:

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

   Please don't.  It might be documented that way, but outline-minor-mode
   behaves very poorly with them.  And it's very hard to "fix"
   outline-minor-mode because it can't tell the difference between
   the case where the three-semi-comment is used for a major heading or
   for commented out code.  I think the doc should be fixed.

But then we should not only change (elisp)Comment Tips, but also
quantify the assertion:

   * Indent each function with `C-M-q' (`indent-sexp') using the
     default indentation parameters.

in (elisp)Coding Conventions, as well as change (probably plenty of)
existing code.  See for instance "describe-text.el", lines 222 and
following.  Note that three semicolons are currently recommended and
used for _several_ purposes other than "major headings", see
(elisp)Comment Tips.  The most important ones are for use
_within a function_.

The fact that we would get trouble with C-M-q if we follow your
suggestion seems to be a real nuisance.  I would not immediately see
how to fix that problem either.

   And it's very hard to "fix" outline-minor-mode because it can't
   tell the difference between the case where the three-semi-comment
   is used for a major heading or for commented out code.

Can outline-minor-mode not "see" that the commented out code is inside
a function or other Lisp form?  I would guess that is pretty rare for
a major heading to occur in the middle of a function.  The commented
out code in "describe-text.el" is _not_ inside a function.  I do not
know whether this code yields problems for outline-minor-mode.
However, on the one hand, one is not going to call C-M-q easily on
commented out code outside functions (so using two semicolons _there_
would not seem that bad) and, on the other, if one gets "really
desperate" one can, in the worst case, place the commented out code
inside a call to `ignore'.  But one could also start (and maybe end)
commented out code outside functions with some standard comment, so
outline-minor-mode (and actually a person reading through the file) can
easily recognize it for what it is.

Anyway, whatever is decided on this, I believe that it is important
that we all follow the _same_ conventions and that these conventions
are clearly and accurately documented.  If we all "do are own thing"
then _both_ outline-minor-mode and C-M-q will have problems and we get
the "worst of both worlds".

Sincerely,

Luc.