[Emacs-diffs] /srv/bzr/emacs/trunk r106619: More updates to Programs chapter of Emacs manual.

[Chong Yidong]

------------------------------------------------------------
revno: 106619
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Mon 2011-12-05 23:20:13 +0800
message:
  More updates to Programs chapter of Emacs manual.
  
  * doc/emacs/programs.texi (Comment Commands): Fix description of for M-; on
  blank lines.  Move documentation of comment-region here.
  (Multi-Line Comments): Clarify the role of comment-multi-line.
  Refer to Comment Commands for comment-region doc.
  (Options for Comments): Refer to Multi-Line Comments for
  comment-multi-line doc, instead of duplicating it.  Fix default
  values of comment-padding and comment-start-skip.
modified:
  doc/emacs/ChangeLog
  doc/emacs/programs.texi

=== modified file 'doc/emacs/ChangeLog'
--- a/doc/emacs/ChangeLog       2011-12-04 16:19:57 +0000
+++ b/doc/emacs/ChangeLog       2011-12-05 15:20:13 +0000
@@ -1,3 +1,13 @@
+2011-12-05  Chong Yidong  <address@hidden>
+
+       * programs.texi (Comment Commands): Fix description of for M-; on
+       blank lines.  Move documentation of comment-region here.
+       (Multi-Line Comments): Clarify the role of comment-multi-line.
+       Refer to Comment Commands for comment-region doc.
+       (Options for Comments): Refer to Multi-Line Comments for
+       comment-multi-line doc, instead of duplicating it.  Fix default
+       values of comment-padding and comment-start-skip.
+
 2011-12-04  Chong Yidong  <address@hidden>
 
        * programs.texi (Program Modes): Mention modes that are not

=== modified file 'doc/emacs/programs.texi'
--- a/doc/emacs/programs.texi   2011-12-04 16:19:57 +0000
+++ b/doc/emacs/programs.texi   2011-12-05 15:20:13 +0000
@@ -850,6 +850,23 @@
 also do spell checking on comments with Flyspell Prog mode
 (@pxref{Spelling}).
 
+  Some major modes have special rules for indenting different kinds of
+comments.  For example, in Lisp code, comments starting with two
+semicolons are indented as if they were lines of code, while those
+starting with three semicolons are supposed to be aligned to the left
+margin and are often used for sectioning purposes.  Emacs understand
+these conventions; for instance, typing @key{TAB} on a comment line
+will indent the comment to the appropriate position.
+
address@hidden
+;; This function is just an example.
+;;; Here either two or three semicolons are appropriate.
+(defun foo (x)
+;;;  And now, the first part of the function:
+  ;; The following line adds one.
+  (1+ x))           ; This line adds one.
address@hidden example
+
 @menu
 * Comment Commands::    Inserting, killing, and aligning comments.
 * Multi-Line Comments:: Commands for adding and editing multi-line comments.
@@ -861,12 +878,12 @@
 @cindex indentation for comments
 @cindex alignment for comments
 
-  The commands in this table insert, kill and align comments:
+  The following commands operate on comments:
 
 @table @asis
 @item @kbd{M-;}
-Insert or realign comment on current line; alternatively, comment or
-uncomment the region (@code{comment-dwim}).
+Insert or realign comment on current line; if the region is active,
+comment or uncomment the region instead (@code{comment-dwim}).
 @item @kbd{C-u M-;}
 Kill comment on current line (@code{comment-kill}).
 @item @kbd{C-x ;}
@@ -877,7 +894,7 @@
 (@code{comment-indent-new-line}).  @xref{Multi-Line Comments}.
 @item @kbd{M-x comment-region}
 @itemx @kbd{C-c C-c} (in C-like modes)
-Add or remove comment delimiters on all the lines in the region.
+Add comment delimiters to all the lines in the region.
 @end table
 
 @kindex M-;
@@ -888,65 +905,61 @@
 different jobs relating to comments, depending on the situation where
 you use it.
 
-  When a region is active, @kbd{M-;} either adds or removes comment
-delimiters on each line of the region.  @xref{Mark}.  If every line in
-the region is a comment, it removes comment delimiters from each;
-otherwise, it adds comment delimiters to each.  You can also use the
-commands @code{comment-region} and @code{uncomment-region} to
-explicitly comment or uncomment the text in the region
-(@pxref{Multi-Line Comments}).  If you supply a prefix argument to
address@hidden;} when a region is active, that specifies how many comment
-delimiters to add or how many to delete.
-
-  If the region is not active, @kbd{M-;} inserts a new comment if
-there is no comment already on the line.  The new comment is normally
-aligned at a specific column called the @dfn{comment column}; if the
-text of the line extends past the comment column, @kbd{M-;} aligns the
-comment start string to a suitable boundary (usually, at least one
-space is inserted).  The comment begins with the string Emacs thinks
-comments should start with (the value of @code{comment-start}; see
-below).  Emacs places point after that string, so you can insert the
-text of the comment right away.  If the major mode has specified a
-string to terminate comments, @kbd{M-;} inserts that string after
-point, to keep the syntax valid.
+  When a region is active (@pxref{Mark}), @kbd{M-;} either adds
+comment delimiters to the region, or removes them.  If every line in
+the region is already a comment, it ``uncomments'' each of those lines
+by removing their comment delimiters.  Otherwise, it adds comment
+delimiters to enclose the text in the region.
+
+  If you supply a prefix argument to @kbd{M-;} when a region is
+active, that specifies the number of comment delimiters to add or
+delete.  A positive argument @var{n} adds @var{n} delimiters, while a
+negative argument @var{-n} removes @var{n} delimiters.
+
+  If the region is not active, and there is no existing comment on the
+current line, @kbd{M-;} adds a new comment to the current line.  If
+the line is blank (i.e.@: empty or containing only whitespace
+characters), the comment is indented to the same position where
address@hidden would indent to (@pxref{Basic Indent}).  If the line is
+non-blank, the comment is placed after the last non-whitespace
+character on the line; normally, Emacs tries putting it at the column
+specified by the variable @code{comment-column} (@pxref{Options for
+Comments}), but if the line already extends past that column, it puts
+the comment at some suitable position, usually separated from the
+non-comment text by at least one space.  In each case, Emacs places
+point after the comment's starting delimiter, so that you can start
+typing the comment text right away.
 
   You can also use @kbd{M-;} to align an existing comment.  If a line
 already contains the comment-start string, @kbd{M-;} realigns it to
-the conventional alignment and moves point after it.  (Exception:
-comments starting in column 0 are not moved.)  Even when an existing
-comment is properly aligned, @kbd{M-;} is still useful for moving
-directly to the start of the text inside the comment.
+the conventional alignment and moves point after the comment's
+starting delimiter.  As an exception, comments starting in column 0
+are not moved.  Even when an existing comment is properly aligned,
address@hidden;} is still useful for moving directly to the start of the
+comment text.
 
 @findex comment-kill
 @kindex C-u M-;
-  @kbd{C-u M-;} kills any comment on the current line, along with the
-whitespace before it.  To reinsert the comment on another line, move
-to the end of that line, do @kbd{C-y}, and then do @kbd{M-;} to
-realign it.
-
-  Note that @kbd{C-u M-;} is not a distinct key; it is @kbd{M-;}
-(@code{comment-dwim}) with a prefix argument.  That command is
-programmed so that when it receives a prefix argument it calls
address@hidden  However, @code{comment-kill} is a valid command
-in its own right, and you can bind it directly to a key if you wish.
-
-  Some major modes have special rules for aligning certain kinds of
-comments in certain contexts.  For example, in Lisp code, comments which
-start with two semicolons are indented as if they were lines of code,
-instead of at the comment column.  Comments which start with three
-semicolons are supposed to start at the left margin and are often used
-for sectioning purposes.  Emacs understands
-these conventions by indenting a double-semicolon comment using @key{TAB},
-and by not changing the indentation of a triple-semicolon comment at all.
-
address@hidden
-;; This function is just an example.
-;;; Here either two or three semicolons are appropriate.
-(defun foo (x)
-;;;  And now, the first part of the function:
-  ;; The following line adds one.
-  (1+ x))           ; This line adds one.
address@hidden example
+  @kbd{C-u M-;} (@code{comment-dwim} with a prefix argument) kills any
+comment on the current line, along with the whitespace before it.
+Since the comment is saved to the kill ring, you can reinsert it on
+another line by moving to the end of that line, doing @kbd{C-y}, and
+then @kbd{M-;} to realign the command.  You can achieve the same
+effect as @kbd{C-u M-;} by typing @kbd{M-x comment-kill}
+(@code{comment-dwim} actually calls @code{comment-kill} as a
+subroutine when it is given a prefix argument).
+
address@hidden C-c C-c (C mode)
address@hidden comment-region
address@hidden uncomment-region
+  The command @kbd{M-x comment-region} is equivalent to calling
address@hidden;} on an active region, except that it always acts on the
+region, even if the mark is inactive.  In C mode and related modes,
+this command is bound to @kbd{C-c C-c}.  The command @kbd{M-x
+uncomment-region} uncomments each line in the region; a numeric prefix
+argument specifies the number of comment delimiters to remove
+(negative arguments specify the number of comment to delimiters to
+add).
 
   For C-like modes, you can configure the exact effect of @kbd{M-;} by
 setting the variables @code{c-indent-comment-alist} and
@@ -962,32 +975,31 @@
 @kindex M-j
 @cindex blank lines in programs
 @findex comment-indent-new-line
-
-  If you are typing a comment and wish to continue it on another line,
-you can use the command @kbd{C-M-j} or @kbd{M-j}
-(@code{comment-indent-new-line}).  If @code{comment-multi-line}
-(@pxref{Options for Comments}) is address@hidden, it moves to a new
-line within the comment.  Otherwise it closes the comment and starts a
-new comment on a new line.  When Auto Fill mode is on, going past the
-fill column while typing a comment causes the comment to be continued
-in just this fashion.
-
address@hidden C-c C-c (C mode)
address@hidden comment-region
-  To turn existing lines into comment lines, use the @kbd{M-x
-comment-region} command (or type @kbd{C-c C-c} in C-like modes).  It
-adds comment delimiters to the lines that start in the region, thus
-commenting them out.  With a negative argument, it does the
-opposite---it deletes comment delimiters from the lines in the region.
-
-  With a positive argument, @code{comment-region} duplicates the last
-character of the comment start sequence it adds; the argument
-specifies how many copies of the character to insert.  Thus, in Lisp
-mode, @kbd{C-u 2 M-x comment-region} adds @samp{;;} to each line.
-Duplicating the comment delimiter is a way of calling attention to the
-comment.  It can also affect how the comment is aligned or indented.
-In Lisp, for proper indentation, you should use an argument of two or
-three, if between defuns; if within a defun, it must be three.
address@hidden comment-multi-line
+  If you are typing a comment and wish to continue it to another line,
+type @kbd{M-j} or @kbd{C-M-j} (@code{comment-indent-new-line}).  This
+breaks the current line, and inserts the necessary comment delimiters
+and indentation to continue the comment.
+
+  For languages with closing comment delimiters (e.g.@: @samp{*/} in
+C), the exact behavior of @kbd{M-j} depends on the value of the
+variable @code{comment-multi-line}.  If the value is @code{nil}, the
+command closes the comment on the old line and starts a new comment on
+the new line.  Otherwise, it opens a new line within the current
+comment delimiters.
+
+  When Auto Fill mode is on, going past the fill column while typing a
+comment also continues the comment, in the same way as an explicit
+invocation of @kbd{M-j}.
+
+  To turn existing lines into comment lines, use @kbd{M-;} with the
+region active, or use @kbd{M-x comment-region}
address@hidden
+(@pxref{Comment Commands}).
address@hidden ifinfo
address@hidden
+as described in the preceding section.
address@hidden ifnotinfo
 
   You can configure C Mode such that when you type a @samp{/} at the
 start of a line in a multi-line block comment, this closes the
@@ -1000,19 +1012,16 @@
 @vindex comment-column
 @kindex C-x ;
 @findex comment-set-column
-  The @dfn{comment column}, the column at which Emacs tries to place
-comments, is stored in the variable @code{comment-column}.  You can
-set it to a number explicitly.  Alternatively, the command @kbd{C-x ;}
-(@code{comment-set-column}) sets the comment column to the column
-point is at.  @kbd{C-u C-x ;} sets the comment column to match the
-last comment before point in the buffer, and then does a @kbd{M-;} to
-align the current line's comment under the previous one.
-
-  The variable @code{comment-column} is per-buffer: setting the variable
-in the normal fashion affects only the current buffer, but there is a
-default value which you can change with @code{setq-default}.
address@hidden  Many major modes initialize this variable for the
-current buffer.
+  As mentioned in @ref{Comment Commands}, when the @kbd{M-j} command
+adds a comment to a line, it tries to place the comment at the column
+specified by the buffer-local variable @code{comment-column}.  You can
+set either the local value or the default value of this buffer-local
+variable in the usual way (@pxref{Locals}).  Alternatively, you can
+type @kbd{C-x ;} (@code{comment-set-column}) to set the value of
address@hidden in the current buffer to the column where point
+is currently located.  @kbd{C-u C-x ;} sets the comment column to
+match the last comment before point in the buffer, and then does a
address@hidden;} to align the current line's comment under the previous one.
 
 @vindex comment-start-skip
   The comment commands recognize comments based on the regular
@@ -1021,39 +1030,32 @@
 than the comment starting delimiter in the strictest sense of the word;
 for example, in C mode the value of the variable is
 @c This stops M-q from breaking the line inside that @code.
address@hidden@w{"/\\*+ *\\|//+ *"}}, which matches extra stars and spaces
-after the @samp{/*} itself, and accepts C++ style comments also.
-(Note that @samp{\\} is needed in Lisp syntax to include a @samp{\} in
-the string, which is needed to deny the first star its special meaning
-in regexp syntax.  @xref{Regexp Backslash}.)
address@hidden@w{"\\(//+\\|/\\*+\\)\\s *"}}, which matches extra stars and
+spaces after the @samp{/*} itself, and accepts C++ style comments
+also.  (Note that @samp{\\} is needed in Lisp syntax to include a
address@hidden in the string, which is needed to deny the first star its
+special meaning in regexp syntax.  @xref{Regexp Backslash}.)
 
 @vindex comment-start
 @vindex comment-end
   When a comment command makes a new comment, it inserts the value of
address@hidden to begin it.  The value of @code{comment-end} is
-inserted after point, so that it will follow the text that you will
-insert into the comment.  When @code{comment-end} is non-empty, it
-should start with a space.  For example, in C mode,
address@hidden has the value @address@hidden"/* "}} and
address@hidden has the value @address@hidden" */"}}.
address@hidden as an opening comment delimiter.  It also inserts
+the value of @code{comment-end} after point, as a closing comment
+delimiter.  For example, in Lisp mode, @code{comment-start} is
address@hidden";"} and @code{comment-end} is @code{""} (the empty string).  In
+C mode, @code{comment-start} is @code{"/* "} and @code{comment-end} is
address@hidden" */"}.
 
 @vindex comment-padding
-  The variable @code{comment-padding} specifies how many spaces
address@hidden should insert on each line between the comment
-delimiter and the line's original text.  The default is 1, to insert
-one space.  @code{nil} means 0.  Alternatively, @code{comment-padding}
-can hold the actual string to insert.
+  The variable @code{comment-padding} specifies a string that the
+commenting commands should insert between the comment delimiter(s) and
+the comment text.  The default, @samp{" "}, specifies a single space.
+Alternatively, the value can be a number, which specifies that number
+of spaces, or @code{nil}, which means no spaces at all.
 
address@hidden comment-multi-line
-  The variable @code{comment-multi-line} controls how @kbd{C-M-j}
-(@code{indent-new-comment-line}) behaves when used inside a comment.
-Specifically, when @code{comment-multi-line} is @code{nil}, the
-command inserts a comment terminator, begins a new line, and finally
-inserts a comment starter.  Otherwise it does not insert the
-terminator and starter, so it effectively continues the current
-comment across multiple lines.  In languages that allow multi-line
-comments, the choice of value for this variable is a matter of taste.
-The default for this variable depends on the major mode.
+  The variable @code{comment-multi-line} controls how @kbd{M-j} and
+Auto Fill mode continue comments over multiple lines.
address@hidden Comments}.
 
 @vindex comment-indent-function
   The variable @code{comment-indent-function} should contain a function