Re: Undocumented hyperlinks in doc strings.

[Luc Teirlinck]

Richard Stallman wrote:

       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.

   That convention, in itself, would not hurt anything.  But if we wanted
   to follow it all the time, what exactly would we make comment-region
   do, for Lisp code?  Would we make it insert two spaces always?  Two
   spaces, when given an arg of 3?  And what would uncomment-region do?
   If we make it try to remove two spaces (when there are two),
   then it would uncomment all the existing commented-out code wrong.

   I am not saying that these answer have to be perfect, but we need
   to pick answers.

The three semicolons seem to be mainly important for commented out
code _inside_ functions, to prevent C-M-q from messing things up
badly.  If it would be considered OK to use two semicolons for
commenting out entire top-level forms, then I believe we would not
even need to worry about comment-region or uncomment-region.  Indeed
the only line that would not automatically get the two spaces anyway
would appear to be the introductory line, like

;; this used:

in the example we have been looking at.

This line has to be written in manually and deleted manually after
uncommenting anyway.  People would only have to type an extra space at
the beginning of that one line they have to type in anyway.

If using three semicolons for commented out entire top level forms
would be important, then things would get more complicated.

Sincerely,

Luc.