[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5. Advanced Editing Features

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.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.1 Entering Mathematics

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 ~.

Command: LaTeX-math-mode

(C-c ~) Toggle LaTeX-math-mode. This is a minor mode rebinding the key 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)
User Option: LaTeX-math-abbrev-prefix

A string containing the prefix of LaTeX-math-mode commands; This value defaults to `.

The variable LaTeX-math-list holds the actual mapping.

User Option: LaTeX-math-list

A list containing key command mappings to use in LaTeX-math-mode. The car of each element is the key and the cdr is the macro name.

User Option: LaTeX-math-menu-unicode

Whether the LaTeX menu should try using Unicode for effect. Your Emacs built must be able to display include Unicode characters in menus for this feature.

AUCTeX’s reference card ‘tex-ref.tex’ includes a list of all math mode commands.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.2 Completion

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’’.

Command: TeX-complete-symbol

(M-<TAB>) Complete TeX symbol before point.

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.

Command: TeX-insert-macro

(C-c C-m or C-c RET) Prompt (with completion) for the name of a TeX macro, and if AUCTeX knows the macro, prompt for each argument.

As a default selection, AUCTeX will suggest the macro last inserted or, as the first choice the value of the variable TeX-default-macro.

User Option: TeX-insert-macro-default-style

Specifies whether 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.

User Option: TeX-default-macro

Default macro to insert when invoking 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

User Option: TeX-electric-escape

If this is non-nil when AUCTeX is loaded, the TeX escape character ‘\’ will be bound to 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.

Command: TeX-electric-macro

Prompt (with completion) for the name of a TeX macro, and if AUCTeX knows the macro, prompt for each argument. Space will complete and exit.

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 Entering Mathematics, or by setting TeX-insert-braces to nil.

User Option: TeX-insert-braces

If non-nil, append a empty pair of braces after inserting a macro.

Completions work because AUCTeX can analyze TeX files, and store symbols in emacs lisp files for later retrieval. See section 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 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] [ ? ]

5.3 Commenting

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.

Command: TeX-comment-or-uncomment-region

(C-c ;) Add or remove ‘%’ from the beginning of each line in the current region. Uncommenting works only if the region encloses solely commented lines. If AUCTeX should not try to guess if the region should be commented or uncommented the commands TeX-comment-region and TeX-uncomment-region can be used to explicitly comment or uncomment the region in concern.

Command: TeX-comment-or-uncomment-paragraph

(C-c %) Add or remove ‘%’ from the beginning of each line in the current paragraph. When removing ‘%’ characters the paragraph is considered to consist of all preceding and succeeding lines starting with a ‘%’, until the first non-comment line.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5.4 Indenting

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 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:

<TAB>

LaTeX-indent-line will indent the current line.

<LFD>

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.

C-j

Alias for <LFD>

User Option: LaTeX-indent-environment-list

List of environments with special indentation. The second element in each entry is the function to calculate the indentation level in columns.

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.

User Option: LaTeX-indent-level

Number of spaces to add to the indentation for each ‘\begin’ not matched by a ‘\end’.

User Option: LaTeX-item-indent

Number of spaces to add to the indentation for ‘\item’’s in list environments.

User Option: TeX-brace-indent-level

Number of spaces to add to the indentation for each ‘{’ not matched by a ‘}’.

User Option: LaTeX-syntactic-comments

If non-nil comments will be filled and indented according to LaTeX syntax. Otherwise they will be filled like normal text.

User Option: TeX-newline-function

Used to specify the function which is called when <RET> is pressed. This will normally be 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] [ ? ]

5.5 Filling

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:

C-c C-q C-p

LaTeX-fill-paragraph will fill and indent the current paragraph.

M-q

Alias for C-c C-q C-p

C-c C-q C-e

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.

C-c C-q C-s

LaTeX-fill-section will fill and indent the current logical sectional unit.

C-c C-q C-r

LaTeX-fill-region will fill and indent the current region.

M-g

Alias for C-c C-q C-r

User Option: LaTeX-fill-break-at-separators

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.

User Option: LaTeX-fill-break-before-code-comments

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.


[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

This document was generated by Aidan Kehoe on December 27, 2016 using texi2html 1.82.