GNU Info
(ccmode)Text Filling and Line Breaking
Text Filling and Line Breaking
******************************
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(1) buffer local
and modifies them according to the language syntax and the style of
line decoration that starts every line in a comment. The style variable
`c-comment-prefix-regexp' contains the regexp used to recognize this
"comment line prefix". The default is `//+\\|\\**', which matches C++
style line comments like
// 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
that variable, please make sure it still matches the comment starter
(i.e. `//') of line comments _and_ the line prefix inside block
comments. Also note that since CC Mode uses the value of
`c-comment-prefix-regexp' to set up several other variables at mode
initialization, you need to reinitialize the program mode if you change
it inside a CC Mode buffer.
Line breaks are by default handled (almost) the same regardless
whether they are made by auto fill mode (Note: Auto Fill.
), 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 (*note Adaptive Fill:
(emacs)Adaptive Fill.) 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 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(2), which handles things like bulleted
lists nicely. There's a convenience function `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)
Normally the comment line prefix inserted for a new line inside a
comment is deduced from other lines in it. However there's one
situation when there's no clue about how the prefix should look, namely
when a block comment is broken for the first time. The string in the
style variable `c-block-comment-prefix'(3) is used in that case. It
defaults to `* ', which makes a comment
/* Got O(n^2) here, which is a Bad Thing. */
break into
/* Got O(n^2) here,
* which is a Bad Thing. */
Note that it won't work to justify the indentation by putting leading
spaces in the `c-block-comment-prefix' string, since CC Mode still uses
the normal indentation engine to indent the line. Thus, the right way
to fix the indentation is by setting the `c' syntactic symbol. It
defaults to `c-lineup-C-comments', which handles the indentation of
most common comment styles, see Note: Indentation Functions.
When auto fill mode is enabled, CC Mode can selectively ignore it
depending on the context the line break would occur in, e.g. to never
break a line automatically inside a string literal. This behavior can
be controlled with the `c-ignore-auto-fill' variable. It takes a list
of symbols for the different contexts where auto-filling never should
occur:
* `string' -- Inside a string or character literal.
* `c' -- Inside a C style block comment.
* `c++' -- Inside a C++ style line comment.
* `cpp' -- Inside a preprocessor directive.
* `code' -- Anywhere else, i.e. in normal code.
By default, `c-ignore-auto-fill' is set to `'(string cpp 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 implementation.
The commands that does the actual work follows.
`M-q' (`c-fill-paragraph')
This is the replacement for `fill-paragraph' in 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(4).
`M-j' (`c-indent-new-comment-line')
This is the replacement for `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-`nil', the
indentation and line prefix are preserved. If inside a comment and
`comment-multi-line' is `nil', a new comment of the same type is
started on the next line and indented as appropriate for comments.
`M-x c-context-line-break'
This is a function that works like `indent-new-comment-line' in
comments and `newline-and-indent' elsewhere, 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.
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
`newline-and-indent' on `RET', you might consider switching to
this function.
---------- Footnotes ----------
(1) `comment-start', `comment-end', `comment-start-skip',
`paragraph-start', `paragraph-separate', `paragraph-ignore-fill-prefix',
`adaptive-fill-mode', `adaptive-fill-regexp', and
`adaptive-fill-first-line-regexp'.
(2) It's available from `http://www.wonderworks.com/'. As of
version 2.12, it does however lack a feature that makes it work
suboptimally when `c-comment-prefix-regexp' matches the empty string
(which it does by default). A patch for that is available from the CC
Mode site.
(3) In versions before 5.26, this variable was called
`c-comment-continuation-stars'. As a compatibility measure, CC Mode
still uses the value on that variable if it's set.
(4) This means that the variables `c-hanging-comment-starter-p' and
`c-hanging-comment-ender-p', which controlled this behavior in earlier
versions of CC Mode, are now obsolete.
automatically generated by info2www version 1.2.2.9