comparison man/programs.texi @ 31025:45d3aa851fff

Document comment-dwim and the new binding of M-;. Document that kill-comment is now an alias for comment-kill.

31024:147670916de0

@subsection Comment Commands

@kindex M-;
@cindex indentation for comments
@findex indent-for-comment

  The comment commands insert, kill and align comments.

@c WideCommands
@table @kbd
@item M-;
Insert or align comment (@code{indent-for-comment}).
@item C-x ;
Set comment column (@code{set-comment-column}).
@item C-u - C-x ;
Kill comment on current line (@code{kill-comment}).
@item C-M-j
Like @key{RET} followed by inserting and aligning a comment
(@code{indent-new-comment-line}).
@item M-x comment-region
Add or remove comment delimiters on all the lines in the region.
@end table

  The command that creates a comment is @kbd{M-;} (@code{indent-for-comment}).
If there is no comment already on the line, a new comment is created,
aligned at a specific column called the @dfn{comment column}.  The comment
is created by inserting the string Emacs thinks comments should start with
(the value of @code{comment-start}; see below).  Point is left after that
string.  If the text of the line extends past the comment column, then the
indentation is done to a suitable boundary (usually, at least one space is
inserted).  If the major mode has specified a string to terminate comments,
that is inserted after point, to keep the syntax valid.

  @kbd{M-;} can also be used to align an existing comment.  If a line
already contains the string that starts comments, then @kbd{M-;} just moves
point after it and reindents it to the conventional place.  Exception:
comments starting in column 0 are not moved.

  Some major modes have special rules for indenting 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

  Even when an existing comment is properly aligned, @kbd{M-;} is still
useful for moving directly to the start of the comment.

@kindex C-u - C-x ;
@findex kill-comment
  @kbd{C-u - C-x ;} (@code{kill-comment}) kills the comment on the current line,
if there is one.  The indentation before the start of the comment is killed
as well.  If there does not appear to be a comment in the line, nothing is
done.  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 - C-x ;} is not a distinct key; it is @kbd{C-x ;} (@code{set-comment-column})
with a negative argument.  That command is programmed so that when it
receives a negative argument it calls @code{kill-comment}.  However,
@code{kill-comment} is a valid command which you could bind directly to a
key if you wanted to.

@node Multi-Line Comments
@subsection Multiple Lines of Comments

@kindex C-M-j

can set it to a number explicitly.  Alternatively, the command @kbd{C-x ;}
(@code{set-comment-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.  Note that @kbd{C-u - C-x ;}
runs the function @code{kill-comment} as described above.

  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

31025:45d3aa851fff

@subsection Comment Commands

@kindex M-;
@cindex indentation for comments
@findex indent-for-comment
@findex comment-dwim

  The comment commands insert, kill and align comments.

@c WideCommands
@table @kbd
@item M-;
Call the comment command that is appropriate for the context
(@code{comment-dwim}).
@item M-x indent-for-comment
Insert or align comment.
@item C-x ;
Set comment column (@code{set-comment-column}).
@item C-u - C-x ;
Kill comment on current line (@code{comment-kill}).
@item C-M-j
Like @key{RET} followed by inserting and aligning a comment
(@code{indent-new-comment-line}).
@item M-x comment-region
Add or remove comment delimiters on all the lines in the region.
@end table

  The command that creates a comment is @kbd{M-x indent-for-comment}.
If there is no comment already on the line, a new comment is created,
aligned at a specific column called the @dfn{comment column}.  The comment
is created by inserting the string Emacs thinks comments should start with
(the value of @code{comment-start}; see below).  Point is left after that
string.  If the text of the line extends past the comment column, then the
indentation is done to a suitable boundary (usually, at least one space is
inserted).  If the major mode has specified a string to terminate comments,
that is inserted after point, to keep the syntax valid.

  @kbd{M-x indent-for-comment} can also be used to align an existing
comment.  If a line already contains the string that starts comments,
then @kbd{M-x indent-for-comment} just moves point after it and
reindents it to the conventional place.  Exception: comments starting in
column 0 are not moved.

  @kbd{M-;} (@code{comment-dwim}) conveniently combines
@code{indent-for-comment} with @code{comment-region} and
@code{uncomment-region}, described below in @ref{Multi-Line Comments},
as appropriate for the current context.  If the region is active and the
Transient Mark mode is on (@pxref{Transient Mark}), @kbd{M-;} invokes
@code{comment-region}, unless the region consists only of comments, in
which case it invokes @code{uncomment-region}.  Otherwise, if the
current line is empty, @kbd{M-;} inserts a comment and indents it.  If
the current line is not empty, @kbd{M-;} invokes @code{comment-kill} if
a numeric argument was given, else it reindents the comment on the
current line.  (The @dfn{dwim} in @code{comment-dwim} is an acronym for
``Do What I Mean''.)

  Some major modes have special rules for indenting 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

  Even when an existing comment is properly aligned, @kbd{M-;} is still
useful for moving directly to the start of the comment.

@kindex C-u - C-x ;
@findex kill-comment
@findex comment-kill
  @kbd{C-u - C-x ;} (@code{comment-kill}) kills the comment on the current line,
if there is one.  The indentation before the start of the comment is killed
as well.  If there does not appear to be a comment in the line, nothing is
done.  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 - C-x ;} is not a distinct key; it is @kbd{C-x ;} (@code{set-comment-column})
with a negative argument.  That command is programmed so that when it
receives a negative argument it calls @code{comment-kill}.  However,
@code{comment-kill} is a valid command which you could bind directly to a
key if you wanted to.  (For compatibility with previous versions,
@code{kill-comment} is provided as an alias to @code{comment-kill}.)

@node Multi-Line Comments
@subsection Multiple Lines of Comments

@kindex C-M-j

can set it to a number explicitly.  Alternatively, the command @kbd{C-x ;}
(@code{set-comment-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.  Note that @kbd{C-u - C-x ;}
runs the function @code{comment-kill} as described above.

  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