| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The previous chapter described how to write the main body of the text easily and with a minimum of errors. In this chapter we will describe some features for entering more specialized sorts of text, for formatting the source by indenting and filling and for navigating through the document.
| 5.1 Entering Mathematics | ||
| 5.2 Completion | Completion of macros | |
| 5.3 Commenting | Commenting text | |
| 5.4 Indenting | Reflecting syntactic constructs with whitespace | |
| 5.5 Filling | Automatic and manual line breaking |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
TeX is written by a mathematician, and has always contained good support for formatting mathematical text. AUCTeX supports this tradition, by offering a special minor mode for entering text with many mathematical symbols. You can enter this mode by typing C-c ~.
LaTeX-math-abbrev-prefix to allow easy typing of
mathematical symbols. ` will read a character from the keyboard,
and insert the symbol as specified in LaTeX-math-list. If given a
prefix argument, the symbol will be surrounded by dollar signs.
You can use another prefix key (instead of `) by setting the
variable LaTeX-math-abbrev-prefix.
To enable LaTeX-math-mode by default, add the following in your `.emacs' file:
(add-hook 'LaTeX-mode-hook 'LaTeX-math-mode) |
LaTeX-math-mode commands;
This value defaults to `.
The variable LaTeX-math-list holds the actual mapping.
LaTeX-math-mode.
The car of each element is the key and the cdr is the macro name.
AUCTeX's reference card `tex-ref.tex' includes a list of all math mode commands.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Emacs lisp programmers probably know the lisp-complete-symbol
command, usually bound to M-TAB. Users of the wonderful
ispell mode know and love the ispell-complete-word command from
that package. Similarly, AUCTeX has a TeX-complete-symbol
command, usually bound to M-TAB. Using
LaTeX-complete-symbol makes it easier to type and remember the
names of long LaTeX macros.
In order to use TeX-complete-symbol, you should write a backslash
and the start of the macro. Typing M-TAB will now complete
as much of the macro, as it unambiguously can. For example, if you type
``\renewc'' and then M-TAB, it will expand to
``\renewcommand''.
A more direct way to insert a macro is with TeX-insert-macro,
bound to C-c C-m. It has the advantage over completion that it
knows about the argument of most standard LaTeX macros, and will
prompt for them. It also knows about the type of the arguments, so it
will for example give completion for the argument to `\include'.
Some examples are listed below.
As a default selection, AUCTeX will suggest the macro last inserted
or, as the first choice the value of the variable
TeX-default-macro.
TeX-insert-macro will ask for all optional
arguments.
If set to the symbol show-optional-args, TeX-insert-macro
asks for optional arguments of TeX macros. If set to
mandatory-args-only, TeX-insert-macro asks only for
mandatory arguments. When TeX-insert-macro is called with prefix
argument (C-u), it's the other way round.
Note that for some macros, there are special mechanisms, e.g.
LaTeX-includegraphics-options-alist.
TeX-insert-macro first time.
A faster alternative is to bind the function TeX-electric-macro
to `\'. This can be done by setting the variable
TeX-electric-escape
TeX-electric-macro
The difference between TeX-insert-macro and
TeX-electric-macro is that space will complete and exit from the
minibuffer in TeX-electric-macro. Use TAB if you merely
want to complete.
By default AUCTeX will put an empty set braces `{}' after a
macro with no arguments to stop it from eating the next whitespace.
This can be stopped by entering LaTeX-math-mode,
see section 5.1 Entering Mathematics, or by setting TeX-insert-braces to nil.
Completions work because AUCTeX can analyze TeX files, and store symbols in emacs lisp files for later retrieval. See section 11. Automatic Customization, for more information.
AUCTeX will also make completion for many macro arguments, for
example existing labels when you enter a `\ref' macro with
TeX-insert-macro or TeX-electric-macro, and BibTeX
entries when you enter a `\cite' macro. For this kind of
completion to work, parsing must be enabled as described in
see section 9. Automatic Parsing of TeX files. For `\cite' you must also make sure that
the BibTeX files have been saved at least once after you enabled
automatic parsing on save, and that the basename of the BibTeX file
does not conflict with the basename of one of TeX files.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
It is often necessary to comment out temporarily a region of TeX or LaTeX code. This can be done with the commands C-c ; and C-c %. C-c ; will comment out all lines in the current region, while C-c % will comment out the current paragraph. Type C-c ; again to uncomment all lines of a commented region, or C-c % again to uncomment all comment lines around point. These commands will insert or remove a single `%' respectively.
TeX-comment-region and TeX-uncomment-region can be used
to explicitly comment or uncomment the region in concern.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Indentation means the addition of whitespace at the beginning of lines to reflect special syntactical constructs. This makes it easier to see the structure of the document, and to catch errors such as a missing closing brace. Thus, the indentation is done for precisely the same reasons that you would indent ordinary computer programs.
Indentation is done by LaTeX environments and by TeX groups, that
is the body of an environment is indented by the value of
LaTeX-indent-level (default 2). Also, items of an `itemize-like'
environment are indented by the value of LaTeX-item-indent,
default -2. If more environments are nested, they are indented
`accumulated' just like most programming languages usually are seen
indented in nested constructs.
You can explicitely indent single lines, usually by pressing TAB,
or marked regions by calling indent-region on it. If you have
auto-fill-mode enabled and a line is broken while you type it,
Emacs automatically cares about the indentation in the following line.
If you want to have a similar behavior upon typing RET, you can
customize the variable TeX-newline-function and change the
default of newline which does no indentation to
newline-and-indent which indents the new line or
reindent-then-newline-and-indent which indents both the current
and the new line.
There are certain LaTeX environments which should be indented in a
special way, like `tabular' or `verbatim'. Those environments
may be specified in the variable LaTeX-indent-environment-list
together with their special indentation functions. Taking the
`verbatim' environment as an example you can see that
current-indentation is used as the indentation function. This
will stop AUCTeX from doing any indentation in the environment if you
hit TAB for example.
There are environments in LaTeX-indent-environment-list which do
not bring a special indentation function with them. This is due to the
fact that first the respective functions are not implemented yet and
second that filling will be disabled for the specified environments.
This shall prevent the source code from being messed up by accidently
filling those environments with the standard filling routine. If you
think that providing special filling routines for such environments
would be an appropriate and challenging task for you, you are invited to
contribute. (See section 5.5 Filling, for further information about the filling
functionality)
The check for the indentation function may be enabled or disabled by
customizing the variable LaTeX-indent-environment-check.
As a side note with regard to formatting special environments: Newer
Emacsen include `align.el' and therefore provide some support for
formatting `tabular' and `tabbing' environments with the
function align-current which will nicely align columns in the
source code.
AUCTeX is able to format commented parts of your code just as any
other part. This means LaTeX environments and TeX groups in
comments will be indented syntactically correct if the variable
LaTeX-syntactic-comments is set to t. If you disable it,
comments will be filled like normal text and no syntactic indentation
will be done.
Following you will find a list of most commands and variables related to indenting with a small summary in each case:
LaTeX-indent-line will indent the current line.
newline-and-indent inserts a new line (much like RET) and
moves the cursor to an appropriate position by the left margin.
Most keyboards nowadays don't have a linefeed key and C-j is
tedious to type. Therefore you can customize AUCTeX to perform
indentation (or to make coffee) upon typing RET as well. The
respective option is called TeX-newline-function.
The filling code currently cannot handle tabular-like environments which will be completely messed-up if you try to format them. This is why most of these environments are included in this customization option without a special indentation function. This will prevent that they get filled.
newline which simply inserts a new line.
In case you want to have AUCTeX do indentation as well when you press
RET, use the built-in functions newline-and-indent or
reindent-then-newline-and-indent. The former inserts a new line
and indents the following line, i.e. it moves the cursor to the right
position and therefore acts as if you pressed LFD. The latter
function additionally indents the current line. If you choose
`Other', you can specify your own fancy function to be called when
RET is pressed.
| [ < ] | [ > ] | [ << ] | [ 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. For
all text modes with text-mode-hook, for all AUCTeX modes with
TeX-mode-hook or for specific modes with
plain-TeX-mode-hook, LaTeX-mode-hook,
ConTeXt-mode-hook or docTeX-mode-hook. 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 explicitely 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 explicitely 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.
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.
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.
| [ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This document was generated by XEmacs shared group account on December, 19 2009
using texi2html 1.65.