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

1 files changed, 14 insertions, 3 deletions

diff --git a/lispref/tips.texi b/lispref/tips.texi
index 585ec8ee475..c78d13f947e 100644
--- 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