[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Filling deals with the insertion of line breaks to prevent lines from
becoming wider than what is specified in fill-column
. The
linebreaks will be inserted automatically if auto-fill-mode
is
enabled. In this case the source is not only filled but also indented
automatically as you write it.
auto-fill-mode
can be enabled for AUCTeX by calling
turn-on-auto-fill
in one of the hooks AUCTeX is running.
See Modes and Hooks. As an example, if you want to enable
auto-fill-mode
in LaTeX-mode
, put the following into your
init file:
(add-hook 'LaTeX-mode-hook #'turn-on-auto-fill) |
You can manually fill explicitly marked regions, paragraphs, environments, complete sections, or the whole buffer. (Note that manual filling in AUCTeX will indent the start of the region to be filled in contrast to many other Emacs modes.)
There are some syntactical constructs which are handled specially with regard to filling. These are so-called code comments and paragraph commands.
Code comments are comments preceded by code or text in the same line.
Upon filling a region, code comments themselves will not get filled.
Filling is done from the start of the region to the line with the code
comment and continues after it. In order to prevent overfull lines in
the source code, a linebreak will be inserted before the last
non-comment word by default. This can be changed by customizing
LaTeX-fill-break-before-code-comments
. If you have overfull
lines with code comments you can fill those explicitly by calling
LaTeX-fill-paragraph
or pressing M-q with the cursor
positioned on them. This will add linebreaks in the comment and indent
subsequent comment lines to the column of the comment in the first line
of the code comment. In this special case M-q only acts on the
current line and not on the whole paragraph.
Lines with ‘\par’ are treated similarly to code comments, i.e. ‘\par’ will be treated as paragraph boundary which should not be followed by other code or text. But it is not treated as a real paragraph boundary like an empty line where filling a paragraph would stop.
Paragraph commands like ‘\section’ or ‘\noindent’ (the list of
commands is defined by LaTeX-paragraph-commands
) are often to be
placed in their own line(s). This means they should not be consecuted
with any preceding or following adjacent lines of text. AUCTeX will
prevent this from happening if you do not put any text except another
macro after the end of the last brace of the respective macro. If
there is other text after the macro, AUCTeX regards this as a sign
that the macro is part of the following paragraph.
Here are some examples:
\begin{quote} text text text text |
\begin{quote}\label{foo} text text text text |
If you press M-q on the first line in both examples, nothing will change. But if you write
\begin{quote} text text text text text |
and press M-q, you will get
\begin{quote} text text text text text |
Besides code comments and paragraph commands, another speciality of
filling in AUCTeX involves commented lines. You should be aware that
these comments are treated as islands in the rest of the LaTeX code
if syntactic filling is enabled. This means, for example, if you try to
fill an environment with LaTeX-fill-environment
and have the
cursor placed on a commented line which does not have a surrounding
environment inside the comment, AUCTeX will report an error.
The relevant commands and variables with regard to filling are:
LaTeX-fill-paragraph
will fill and indent the current paragraph.
Alias for C-c C-q C-p
LaTeX-fill-environment
will fill and indent the current
environment. This may e.g. be the ‘document’ environment, in which case
the entire document will be formatted.
LaTeX-fill-section
will fill and indent the current logical
sectional unit.
LaTeX-fill-region
will fill and indent the current region.
List of separators before or after which respectively linebreaks will be inserted if they do not fit into one line. The separators can be curly braces, brackets, switches for inline math (‘$’, ‘\(’, ‘\)’) and switches for display math (‘\[’, ‘\]’). Such formatting can be useful to make macros and math more visible or to prevent overfull lines in the LaTeX source in case a package for displaying formatted TeX output inside the Emacs buffer, like preview-latex, is used.
Code comments are comments preceded by some other text in the same line.
When a paragraph containing such a comment is to be filled, the comment
start will be seen as a border after which no line breaks will be
inserted in the same line. If the option
LaTeX-fill-break-before-code-comments
is enabled (which is the
default) and the comment does not fit into the line, a line break will
be inserted before the last non-comment word to minimize the chance that
the line becomes overfull.
A list of macro names (without leading backslash) for whose arguments
filling should be disabled. Typically, you will want to add macros here
which have long, multi-line arguments. An example is
\pgfplotstabletypeset
from the pgfplotstable package which is
used as shown in the following listing:
\pgfplotstabletypeset[skip first n=4]{% XYZ Format, Version 1.234 Date 2010-09-01 @author Mustermann A B C 1 2 3 4 5 6 }
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This document was generated on January 17, 2024 using texi2html 1.82.