From: Eli Zaretskii Date: Tue, 22 Aug 2000 09:02:40 +0000 (+0000) Subject: Document comment-dwim and the new binding of M-;. X-Git-Tag: emacs-pretest-21.0.90~2114 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=f91db65b1f9ed45134ecf73cb4108a7e50e10df8;p=emacs.git Document comment-dwim and the new binding of M-;. Document that kill-comment is now an alias for comment-kill. --- diff --git a/man/programs.texi b/man/programs.texi index fd5fd2737d9..b2a1f4c15cc 100644 --- a/man/programs.texi +++ b/man/programs.texi @@ -1217,17 +1217,21 @@ provides special commands for editing and inserting comments. @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-; -Insert or align comment (@code{indent-for-comment}). +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{kill-comment}). +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}). @@ -1235,7 +1239,7 @@ Like @key{RET} followed by inserting and aligning a comment 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}). + 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 @@ -1245,10 +1249,24 @@ 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. + @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 @@ -1275,16 +1293,18 @@ 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, +@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{kill-comment}. However, -@code{kill-comment} is a valid command which you could bind directly to a -key if you wanted to. +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 @@ -1334,7 +1354,7 @@ can set it to a number explicitly. Alternatively, the command @kbd{C-x ;} 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. +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