Re: Undocumented hyperlinks in doc strings.

[Stefan Monnier]

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

I don't understand what you mean here.
My recommendation is to use two semi-colons instead of three.
The indentation of those semi-colons is the same as normal code
and works just fine for commented-out code (this style is of
commenting-out is already used at many places).

One problem is that comment-region by default puts the comment markers
in column 0.  But setting comment-style to any value other than `plain'
addresses this issue.

> in (elisp)Coding Conventions, as well as change (probably plenty of)
> existing code.

Some of the code uses the documented convention while other uses
the convention that I propose.  I don't know which is more common,
but neither is "marginal".  We've lived with this "inconsistency"
without even thinking about it for many years, so I see no reason
to go and "fix" it all at once for the sake of it.  But I do turn
the three-semi to two-semi when I come across them with outline-minor-mode.

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

I know, and the difficulty to tell one case from the radically different
other is the reason why I think the doc is broken.

> The fact that we would get trouble with C-M-q if we follow your
> suggestion seems to be a real nuisance.

I have no idea what trouble you're referring to.  I use M-C-q on a regular
basis without any trouble whatsoever.

> Can outline-minor-mode not "see" that the commented out code is inside
> a function or other Lisp form?

It's pretty difficult and costly to do so (need to extend outline.el
so as to allow more than just regexps to specify headings).  Furthermore it
won't work right in the case where three-semi commented-out code code
is outside of a lisp form (pretty common) and it won't work right either
when a heading is inside a lisp form (not a real concern, but possible
and meaningful).

> commented out code outside functions (so using two semicolons _there_
> would not seem that bad) and, on the other, if one gets "really

Outside of functions, two-semi and three-semi behave just the same,
indentationwise, so it's really a non-issue.

> then _both_ outline-minor-mode and C-M-q will have problems and we get
> the "worst of both worlds".

C-M-q doesn't need to differentiate between major headings and other
comments, so as far as I know, it is completely unaffected by the
issue discussed here.  Unless I missed something, of course.


        Stefan