(Comment Tips): Document the new conventions for commenting out code.

diff --git a/lispref/tips.texi b/lispref/tips.texi
index 585ec8ee4752f74e35878479798c22ffa67eaacc..c78d13f947e52f04a0c3e8101d3909522397d627 100644 (file)
--- a/lispref/tips.texi
+++ b/lispref/tips.texi
@@ -802,19 +802,30 @@ Comments that start with three semicolons, @samp{;;;}, should start at
 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.
+semicolons depends on whether the comment should be considered a
+``heading'' by Outline minor mode.  By default, comments starting with
+at least three semicolons (followed by a single space and a
+non-whitespace character) 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.
+they remain at the left margin.  By default, 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.
 
 @smallexample
 (defun foo (a)
-;;; This is no longer necessary.
+;;;  This is no longer necessary.
 ;;;  (force-mode-line-update)
   (message "Finished with %s" a))
 @end smallexample
 
+When commenting out entire functions, use two semicolons.
+
 @item ;;;;
 Comments that start with four semicolons, @samp{;;;;}, should be aligned
 to the left margin and are used for headings of major sections of a