[Emacs-diffs] trunk r114546: * doc/lispref/tips.texi (Comment Tips): Discourage use of triple semi-colons

[Stefan Monnier]

------------------------------------------------------------
revno: 114546
revision-id: address@hidden
parent: address@hidden
committer: Stefan Monnier <address@hidden>
branch nick: trunk
timestamp: Sun 2013-10-06 23:46:32 -0400
message:
  * doc/lispref/tips.texi (Comment Tips): Discourage use of triple semi-colons
  for non-headings.
modified:
  doc/lispref/ChangeLog          changelog-20091113204419-o5vbwnq5f7feedwu-6155
  doc/lispref/tips.texi          tips.texi-20091113204419-o5vbwnq5f7feedwu-6217

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2013-10-05 11:49:02 +0000
+++ b/doc/lispref/ChangeLog     2013-10-07 03:46:32 +0000
@@ -1,3 +1,8 @@
+2013-10-07  Stefan Monnier  <address@hidden>
+
+       * tips.texi (Comment Tips): Discourage use of triple semi-colons for
+       non-headings.
+
 2013-10-05  Xue Fuqiao  <address@hidden>
 
        * syntax.texi (Categories): Add an index for category sets.

=== modified file 'doc/lispref/tips.texi'
--- a/doc/lispref/tips.texi     2013-06-26 15:22:21 +0000
+++ b/doc/lispref/tips.texi     2013-10-07 03:46:32 +0000
@@ -836,10 +836,10 @@
 
 @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 @@
 
 @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.
-
address@hidden
-(defun foo (a)
-;;;  This is no longer necessary.
-;;;  (force-mode-line-update)
-  (message "Finished with %s" a))
address@hidden 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.