* doc/lispref/tips.texi (Comment Tips): Discourage use of triple semi-colons

for non-headings.

2 files changed, 12 insertions, 23 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index ce2ff2e1665..0a89dbea3d9 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,8 @@
+2013-10-07  Stefan Monnier  <monnier@iro.umontreal.ca>
+
+        * tips.texi (Comment Tips): Discourage use of triple semi-colons for
+        non-headings.
+
 2013-10-05  Xue Fuqiao  <xfq.free@gmail.com>
 
         * syntax.texi (Categories): Add an index for category sets.
diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi
index 2e3760e573e..26d81f738fc 100644
--- a/doc/lispref/tips.texi
+++ b/doc/lispref/tips.texi
@@ -836,10 +836,10 @@ For example:
 
 @smallexample
 @group
-(setq base-version-list                 ; there was a base
+(setq base-version-list                 ; There was a base
       (assoc (substring fn 0 start-vn)  ; version to which
              file-version-assoc-list))  ; this looks like
-                                        ; a subversion
+                                        ; a subversion.
 @end group
 @end smallexample
 
@@ -877,30 +877,14 @@ strings, though.
 
 @item ;;;
 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 depends on whether the comment should be considered a
+the left margin.  We use them
+for comments which 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 fewer 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.  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.
-;;;  (force-mode-line-update)
-  (message "Finished with %s" a))
-@end smallexample
+with two or fewer are not.  Historically, triple-semicolon comments have
+also been used for commenting out lines within a function, but this use
+is discouraged.
 
 When commenting out entire functions, use two semicolons.