|[ < ]||[ > ]||[ << ]||[ Up ]||[ >> ]||[Top]||[Contents]||[Index]||[ ? ]|
Since there's a lot of normal text in comments and string literals, CC Mode provides features to edit these like in text mode. The goal is to do it as seamlessly as possible, i.e. you can use auto fill mode, sentence and paragraph movement, paragraph filling, adaptive filling etc wherever there's a piece of normal text without having to think much about it. CC Mode should keep the indentation, fix the comment line decorations, and so on, for you. It does that by hooking in on the different line breaking functions and tuning relevant variables as necessary.
To make Emacs recognize comments and treat text in them as normal paragraphs, CC Mode makes several standard variables(11) buffer local and modifies them according to the language syntax and the comment line prefix.
// blah blah
with two or more slashes in front of them, and C style block comments like
/* * blah blah */
with zero or more stars at the beginning of every line. If you change
this variable, please make sure it still matches the comment starter
//) of line comments and the line prefix inside
Also note that since CC Mode uses the value of
c-comment-prefix-regexp to set up several other variables at mode
initialization, there won't be any effect if you just change it inside a
CC Mode buffer. You need to call the command
c-setup-paragraph-variables too, to update those other variables with
the new value. That's also the case if you modify this variable in a
mode hook, since CC Mode sets up all variables before calling them.
Line breaks are by default handled (almost) the same regardless whether
they are made by auto fill mode (see section `Auto Fill' in The Emacs Editor), paragraph filling (e.g. with M-q), or explicitly with
M-j or similar methods. In string literals, the new line gets the
same indentation as the previous nonempty line (may be changed with the
string syntactic symbol). In comments, CC Mode uses
c-comment-prefix-regexp to adapt the line prefix from the other
lines in the comment.
CC Mode uses adaptive fill mode (see section `Adaptive Fill' in The Emacs Editor) to make Emacs correctly keep the line prefix when filling paragraphs. That also makes Emacs preserve the text indentation inside the comment line prefix. E.g. in the following comment, both paragraphs will be filled with the left margins of the texts kept intact:
/* Make a balanced b-tree of the nodes in the incoming * stream. But, to quote the famous words of Donald E. * Knuth, * * Beware of bugs in the above code; I have only * proved it correct, not tried it. */
It's also possible to use other adaptive filling packages, notably Kyle
E. Jones' Filladapt package(12),
which handles things like bulleted lists nicely. There's a convenience
c-setup-filladapt that tunes the relevant variables in
Filladapt for use in CC Mode. Call it from a mode hook, e.g. with
something like this in your `.emacs':
(defun my-c-mode-common-hook () (c-setup-filladapt) (filladapt-mode 1)) (add-hook 'c-mode-common-hook 'my-c-mode-common-hook)
/* Got O(n^2) here, which is a Bad Thing. */
/* Got O(n^2) here, * which is a Bad Thing. */
Note that it won't work to adjust the indentation by putting leading
c-block-comment-prefix, since CC Mode still uses the
normal indentation engine to indent the line. Thus, the right way to
fix the indentation is by customizing the
c syntactic symbol. It
c-lineup-C-comments, which handles the indentation of
most common comment styles, see 11. Indentation Functions.
c-ignore-auto-fill is set to
code), which means that auto-filling only occurs in comments when
auto-fill mode is activated. In literals, it's often desirable to have
explicit control over newlines. In preprocessor directives, the
necessary `\' escape character before the newline is not
automatically inserted, so an automatic line break would produce invalid
code. In normal code, line breaks are normally dictated by some logical
structure in the code rather than the last whitespace character, so
automatic line breaks there will produce poor results in the current
The commands that do the actual work follow.
fill-paragraphin CC Mode buffers. It's used to fill multiline string literals and both block and line style comments. In Java buffers, the Javadoc markup words are recognized as paragraph starters. The line oriented Pike autodoc markup words are recognized in the same way in Pike mode.
The function keeps the comment starters and enders of block comments as they were before the filling. This means that a comment ender on the same line as the paragraph being filled will be filled with the paragraph, and one on a line by itself will stay as it is. The comment starter is handled similarly(15).
indent-new-comment-line. It breaks the line at point and indents the new line like the current one.
If inside a comment and
comment-multi-line is non-
indentation and line prefix are preserved. If inside a comment and
nil, a new comment of the same type
is started on the next line and indented as appropriate for comments.
Note that CC Mode sets
startup. The reason is that M-j could otherwise produce sequences
of single line block comments for texts that should logically be treated
as one comment, and the rest of the paragraph handling code
(e.g. M-q and M-a) can't cope with that, which would lead to
indent-new-comment-linein comments and
newline-and-indentelsewhere, thus combining those two in a way that uses each one in the context it's best suited for. I.e. in comments the comment line prefix and indentation is kept for the new line, and in normal code it's indented according to context by the indentation engine.
In macros it acts like
newline-and-indent but additionally
inserts and optionally aligns the line ending backslash so that the
macro remains unbroken. See section 6. Macro Handling, for details about the
It's not bound to a key by default, but it's intended to be used on the
RET key. If you like the behavior of
RET, you should consider switching to this function.
c-context-line-breakis to RET. I.e. it works just like
c-context-line-breakbut leaves the point before the inserted line break.
|[ << ]||[ >> ]||[Top]||[Contents]||[Index]||[ ? ]|