From ebf10822d1ce7579624ddf78a14f9bf114268888 Mon Sep 17 00:00:00 2001 From: Chong Yidong Date: Mon, 5 Dec 2011 23:20:13 +0800 Subject: [PATCH] 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. --- doc/emacs/ChangeLog | 10 ++ doc/emacs/programs.texi | 246 ++++++++++++++++++++-------------------- 2 files changed, 134 insertions(+), 122 deletions(-) diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog index df1812d27ec..894a5901295 100644 --- a/doc/emacs/ChangeLog +++ b/doc/emacs/ChangeLog @@ -1,3 +1,13 @@ +2011-12-05 Chong Yidong + + * 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 * programs.texi (Program Modes): Mention modes that are not diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi index 66f7a49faab..c88535a076b 100644 --- a/doc/emacs/programs.texi +++ b/doc/emacs/programs.texi @@ -850,6 +850,23 @@ provides special commands for editing and inserting comments. It can 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. + +@example +;; 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. +@end example + @menu * Comment Commands:: Inserting, killing, and aligning comments. * Multi-Line Comments:: Commands for adding and editing multi-line comments. @@ -861,12 +878,12 @@ also do spell checking on comments with Flyspell Prog mode @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 @@ Like @key{RET} followed by inserting and aligning a comment (@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 @@ I Mean''; it indicates that this command can be used for many 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 -@kbd{M-;} 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 +@key{TAB} 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, +@kbd{M-;} 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 -@code{comment-kill}. 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. + @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). -@example -;; 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. -@end example +@kindex C-c C-c (C mode) +@findex comment-region +@findex uncomment-region + The command @kbd{M-x comment-region} is equivalent to calling +@kbd{M-;} 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 @@ the brace rather than at @code{comment-column}. For full details see @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 non-@code{nil}, 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. - -@kindex C-c C-c (C mode) -@findex 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. +@vindex 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} +@ifinfo +(@pxref{Comment Commands}). +@end ifinfo +@ifnotinfo +as described in the preceding section. +@end 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 @@ comment. Enable the @code{comment-close-slash} clean-up for this. @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}. -@xref{Locals}. 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 +@code{comment-column} 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 +@kbd{M-;} 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 @@ Make sure this regexp does not match the null string. It may match more 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. -@code{@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}.) +@code{@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 +@samp{\} 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 -@code{comment-start} 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, -@code{comment-start} has the value @w{@code{"/* "}} and -@code{comment-end} has the value @w{@code{" */"}}. +@code{comment-start} 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 +@samp{";"} and @code{comment-end} is @code{""} (the empty string). In +C mode, @code{comment-start} is @code{"/* "} and @code{comment-end} is +@code{" */"}. @vindex comment-padding - The variable @code{comment-padding} specifies how many spaces -@code{comment-region} 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. - -@vindex 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-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. + + The variable @code{comment-multi-line} controls how @kbd{M-j} and +Auto Fill mode continue comments over multiple lines. +@xref{Multi-Line Comments}. @vindex comment-indent-function The variable @code{comment-indent-function} should contain a function -- 2.39.2