Comment conventions.

Comment conventions.

[Luc Teirlinck]

In mid-October, we reached consensus to change the current conventions
for commenting out code, as documented in (elisp)Comment Tips, to
better adapt them to outline-minor-mode.  This was discussed (as a
side issue) in a thread titled "Undocumented hyperlinks in doc strings".

The new conventions were to use two semicolons to comment out entire
functions and three semicolons to comment out part of functions,
indenting any introductory comment by at least two spaces to allow
outline-minor-mode to distinguish.  We then apparently forgot about it
and, in as far as I know, nothing was done to document or implement
this.

What about the following changes to lisp-mode.el and tips.texi?

===File ~/lisp-mode-diff====================================
*** lisp-mode.el.~1.152.~	Tue Sep  2 07:41:50 2003
--- lisp-mode.el	Mon Feb  9 18:50:51 2004
***************
*** 182,188 ****
    (make-local-variable 'parse-sexp-ignore-comments)
    (setq parse-sexp-ignore-comments t)
    (make-local-variable 'outline-regexp)
!   (setq outline-regexp ";;;;* \\|(")
    (make-local-variable 'outline-level)
    (setq outline-level 'lisp-outline-level)
    (make-local-variable 'comment-start)
--- 182,188 ----
    (make-local-variable 'parse-sexp-ignore-comments)
    (setq parse-sexp-ignore-comments t)
    (make-local-variable 'outline-regexp)
!   (setq outline-regexp ";;;;* [^ \t\n]\\|(")
    (make-local-variable 'outline-level)
    (setq outline-level 'lisp-outline-level)
    (make-local-variable 'comment-start)
============================================================

===File ~/tips-diff=========================================
*** tips.texi.~1.55.~	Tue Dec 30 17:39:18 2003
--- tips.texi	Mon Feb  9 19:54:33 2004
***************
*** 802,816 ****
  the left margin.  These are used, occasionally, for comments within
  functions that should start at the margin.  We also use them sometimes
  for comments that are between functions---whether to use two or three
! semicolons there is a matter of style.
  
  Another use for triple-semicolon comments is for commenting out lines
  within a function.  We use three semicolons for this precisely so that
! they remain at the left margin.
  
  @smallexample
  (defun foo (a)
! ;;; This is no longer necessary.
  ;;;  (force-mode-line-update)
    (message "Finished with %s" a))
  @end smallexample
--- 802,826 ----
  the left margin.  These are used, occasionally, for comments within
  functions that should start at the margin.  We also use them sometimes
  for comments that are between functions---whether to use two or three
! semicolons depends on whether the comment should be considered a
! ``heading'' by @code{outline-minor-mode}.  By default, comments
! starting with at least three semicolons are considered headings,
! comments starting with two or less are not.
  
  Another use for triple-semicolon comments is for commenting out lines
  within a function.  We use three semicolons for this precisely so that
! they remain at the left margin.  @code{outline-minor-mode} does not
! consider a comment to be a heading (even if it starts with at least
! three semicolons) if the semicolons are followed by at least two
! spaces.  Thus, if you add an introductory comment to the commented out
! code, make sure to indent it by at least two spaces after the three
! semicolons.
! 
! When commenting out entire functions, use two semicolons.
  
  @smallexample
  (defun foo (a)
! ;;;  This is no longer necessary.
  ;;;  (force-mode-line-update)
    (message "Finished with %s" a))
  @end smallexample
============================================================