Commit ebf10822 authored by Chong Yidong's avatar Chong Yidong
Browse files

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.
parent e7926664
2011-12-05 Chong Yidong <cyd@gnu.org>
* 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 <cyd@gnu.org>
* programs.texi (Program Modes): Mention modes that are not
......
......@@ -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
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment