From 6de913c47e8efa3d2e234cb78c4c28ad681cfd21 Mon Sep 17 00:00:00 2001 From: Stefan Monnier Date: Sun, 6 Oct 2013 23:46:32 -0400 Subject: [PATCH] * doc/lispref/tips.texi (Comment Tips): Discourage use of triple semi-colons for non-headings. --- doc/lispref/ChangeLog | 5 +++++ doc/lispref/tips.texi | 30 +++++++----------------------- 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 + + * tips.texi (Comment Tips): Discourage use of triple semi-colons for + non-headings. + 2013-10-05 Xue Fuqiao * 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. -- 2.39.5