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

# 6. Controlling the Display of Source Code

It is often desirable to get visual help of what markup code in a text actually does whithout having to decipher it explicitely. For this purpose Emacs and AUCTeX provide font locking (also known as syntax highlighting) which visually sets off markup code like macros or environments by using different colors or fonts. For example text to be typeset in italics can be displayed with an italic font in the editor as well, or labels and references get their own distinct color.

While font locking helps you grasp the purpose of markup code and separate markup from content, the markup code can still be distracting. AUCTeX lets you hide those parts and show them again at request with its built-in support for hiding macros and environments which we call folding here.

Besides folding of macros and environments, AUCTeX provides support for Emacs' outline mode which lets you narrow the buffer content to certain sections of your text by hiding the parts not belonging to these sections.

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

## 6.1 Font Locking

Font locking is supposed to improve readability of the source code by highlighting certain keywords with different colors or fonts. It thereby lets you recognize the function of markup code to a certain extent without having to read the markup command. For general information on controlling font locking with Emacs' font lock mode, see section Font Lock Mode' in GNU Emacs Manual.

User Option: TeX-install-font-lock
Once font locking is enabled globally or for the major modes provided by AUCTeX, the font locking patterns and functionality of font-latex are activated by default. You can switch to a different font locking scheme or disable font locking in AUCTeX by customizing the variable TeX-install-font-lock.

Besides font-latex AUCTeX ships with a scheme which is derived from Emacs' default LaTeX mode and activated by choosing tex-font-setup. Be aware that this scheme is not coupled with AUCTeX's style system and not the focus of development. Therefore and due to font-latex being much more feature-rich the following explanations will only cover font-latex.

In case you want to hook in your own fontification scheme, you can choose other and insert the name of the function which sets up your font locking patterns. If you want to disable fontification in AUCTeX completely, choose ignore.

font-latex provides many options for customization which are accessible with M-x customize-group RET font-latex RET. For this description the various options are explained in conceptional groups.

## Macros

Highlighting of macros can be customized by adapting keyword lists which can be found in the customization group font-latex-keywords. The lists contain names of macros without the leading backslash.

Three types of macros can be handled differently with respect to fontification:

1. Commands of the form \foo[bar]{baz}' which consist of the macro itself, optional arguments in square brackets and mandatory arguments in curly braces. For the command itself the face font-lock-keyword-face will be used and for the optional arguments the face font-lock-variable-name-face. The face applied to the mandatory argument depends on the macro class represented by the respective built-in variables.
2. Declaration macros of the form {\foo text}' which consist of the macro which may be enclosed in a TeX group together with text to be affected by the macro. In case a TeX group is present, the macro will get the face font-lock-keyword-face and the text will get the face configured for the respective macro class. If no TeX group is present, the latter face will be applied to the macro itself.
3. Simple macros of the form \foo' which do not have any arguments or groupings. The respective face will be applied to the macro itself.

### General macro classes

font-latex provides keyword lists for different macro classes which are described in the following table:

font-latex-match-function-keywords
Keywords for macros defining or related to functions, like \newcommand'.
Type: \macro[...]{...}'
Face: font-lock-function-name-face

font-latex-match-reference-keywords
Keywords for macros defining or related to references, like \ref'.
Type: \macro[...]{...}'
Face: font-lock-reference-face

font-latex-match-textual-keywords
Keywords for macros specifying textual content, like \caption'.
Type: \macro[...]{...}'
Face: font-lock-type-face

font-latex-match-variable-keywords
Keywords for macros defining or related to variables, like \setlength'.
Type: \macro[...]{...}{...}'
Face: font-lock-variable-name-face

font-latex-match-warning-keywords
Keywords for important macros, e.g. affecting line or page break, like \clearpage'.
Type: \macro'
Face: font-latex-warning-face

### Sectioning commands

Sectioning commands are macros like \chapter' or \section'. For these commands there are two fontification schemes which may be selected by customizing the variable font-latex-title-fontify.

User Option: font-latex-title-fontify
Per default sectioning commands will be shown in a larger, proportional font, which corresponds to the value height' for this variable. The font size varies with the sectioning level, e.g. \part' will have a larger font than \subsection'. font-latex provides four different levels. The respective keyword lists are described in the following table. If you rather like to use the base font and a different color, set the variable to color'. In this case the face font-lock-type-face will be used to fontify the argument of the command.

font-latex-match-title-1-keywords
Keywords for level 1 sectioning commands.
Face: font-latex-title-1-face

font-latex-match-title-2-keywords
Keywords for level 2 sectioning commands.
Face: font-latex-title-2-face

font-latex-match-title-3-keywords
Keywords for level 3 sectioning commands.
Face: font-latex-title-3-face

font-latex-match-title-4-keywords
Keywords for level 4 sectioning commands.
Face: font-latex-title-4-face

### Commands for changing fonts

LaTeX provides various macros for changing fonts or font attributes. For example, you can select an italic font with \textit{...}' or bold with \textbf{...}'. An alternative way to specify these fonts is to use special macros in TeX groups, like {\itshape ...}' for italics and {\bfseries ...}' for bold. As mentioned above, we call the former variants commands and the latter declarations.

Besides the macros for changing fonts provided by LaTeX there is an infinite number of other macros--either defined by yourself for logical markup or defined by macro packages--which affect the font in the typeset text. While LaTeX's built-in macros and macros of packages known by AUCTeX are already handled by font-latex, different keyword lists per type style and macro type are provided for entering your own macros which are listed in the table below.

font-latex-match-bold-command-keywords
Keywords for commands specifying a bold type style.
Face: font-latex-bold-face
font-latex-match-italic-command-keywords
Keywords for commands specifying an italic font.
Face: font-latex-italic-face
font-latex-match-math-command-keywords
Keywords for commands specifying a math font.
Face: font-latex-math-face
font-latex-match-type-command-keywords
Keywords for commands specifying a typewriter font.
Face: font-lock-type-face
font-latex-match-bold-declaration-keywords
Keywords for declarations specifying a bold type style.
Face: font-latex-bold-face
font-latex-match-italic-declaration-keywords
Keywords for declarations specifying an italic font.
Face: font-latex-italic-face
font-latex-match-type-declaration-keywords
Keywords for declarations specifying a typewriter font.
Face: font-latex-type-face

### User-defined keyword classes

In case the customization options explained above do not suffice for your needs, you can specify your own keyword classes by customizing the variable font-latex-user-keyword-classes.

User Option: font-latex-user-keyword-classes
Every keyword class consists of four parts, a name, a list of keywords, a face and a specifier for the type of macros to be highlighted.

When adding new entries, you have to use unique values for the class names, i.e. they must not clash with names of the built-in keyword classes or other names given by you. Additionally the names must not contain spaces.

The keywords are names of commands you want to match omitting the leading backslash.

The face argument can either be an existing face or font specifications made by you. (The latter option is not available on XEmacs.)

There are three alternatives for the type of keywords---"Command with arguments", "Declaration inside TeX group" and "Command without arguments"---which correspond with the macro types explained above.

## Quotes

Text in quotation marks is displayed with the face font-latex-string-face. Besides the various forms of opening and closing double and single quotation marks so-called guillemets (<<, >>) can be used for quoting. Because there are two styles of using them--French style: << text >>; German style: >>text<<---you can customize the variable font-latex-quotes to tell font-latex which type you are using.

User Option: font-latex-quotes
Set the value to german' if you are using >>German quotes<< and to french' if you are using << French quotes >>. font-latex will recognize the different ways these quotes can be given in your source code, i.e. ("<', ">'), (<<', >>') and the respective 8-bit variants.

## Subscript and superscript in math

In order to make math constructs more readable, font-latex displays subscript and superscript parts in a smaller font and raised or lowered respectively. This fontification feature can be controlled with the variables font-latex-fontify-script and font-latex-script-display.

User Option: font-latex-fontify-script
If non-nil, fontify subscript and superscript strings.

Note that this feature is not available on XEmacs, for whicht it is disabled per default. In GNU Emacs raising and lowering is not enabled for versions 21.3 and before due to it working not properly.

User Option: font-latex-script-display
Display specification for subscript and superscript content. The car is used for subscript, the cdr is used for superscript. The feature is implemented using so-called display properties. For information on what exactly to specify for the values, see section Other Display Specifications' in GNU Emacs Lisp Reference Manual.

## Verbatim macros and environments

Usually it is not desirable to have content to be typeset verbatim highlighted according to LaTeX syntax. Therefore this content will be fontified uniformly with the face font-latex-verbatim-face.

font-latex differentiates three different types of verbatim constructs for fontification and consequently provides three keyword lists for customization.

User Option: font-latex-verb-like-commands
List of commands with the form \foo|...|' to be fontified as verbatim without the leading backslash. (The delimiters for the command's argument can be any character except an asterisk.)

User Option: font-latex-verbatim-macros
List of macros with the form \foo{...}' to be fontified as verbatim without the leading backslash. In contrast to font-latex-verb-like-commands the macro's argument is enclosed in a TeX group and not two arbitrary characters.

User Option: font-latex-verbatim-environments
List of environments the content of which should be fontified as verbatim.

## Multi-line fontification

Font locking in LaTeX source code often involves constructs spanning more than one line of text. For these constructs to be handled correctly GNU Emacs as well as font-latex provide mechanisms for multi-line fontification which can be controlled by the variable font-latex-do-multi-line.

User Option: font-latex-do-multi-line
Control multi-line fontification.

Setting the variable to t will enable font-latex's mechanism, setting it to nil will disable it. Setting it to try-font-lock' (the default) will use font-lock's mechanism if available and font-latex's method if not.

Setting this variable will only have effect after resetting buffers controlled by font-latex or restarting Emacs.

## Faces

In case you want to change the colors and fonts used by font-latex please refer to the faces mentioned in the explanations above and use M-x customize-face RET <face> RET. All faces defined by font-latex are accessible through a customization group by typing M-x customize-group RET font-latex-highlighting-faces RET.

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

## 6.2 Folding Macros and Environments

There can be macros and environments which have content that is not part of the text body you are writing, like footnotes and citations. Those enclose text which you often only want to see while actually editing it and which otherwise distract your view of the document body. Similarly there are macros where you are not interested in viewing the macro besides its content but rather want to see the content only, like font specifiers where the content might already be fontified in a special way by font locking.

With AUCTeX's folding functionality you can collapse those items and replace them by either a fixed string or the content of one of their arguments instead. If you want to make the original text visible again temporarily in order to view or edit it, move point sideways onto the placeholder (also called display string) or left-click with the mouse pointer on it. (The latter is currently only supported on GNU Emacs.) The macro or environment will unfold automatically, stay open as long as point is inside of it and collapse again once you move point out of it. (Note that folding of environments currently does not work in every AUCTeX mode.)

In order to use this feature, you have to activate TeX-fold-mode which will activate the auto-reveal feature and the necessary commands to hide and show macros and environments. You can activate the mode in a certain buffer by typing the command M-x TeX-fold-mode RET or using the keyboard shortcut C-c C-o C-f. If you want to use it every time you edit a LaTeX document, add it to a hook:

 (add-hook 'LaTeX-mode-hook '(lambda () (TeX-fold-mode 1))) 

If it should be activated in all AUCTeX modes, use TeX-mode-hook instead of LaTeX-mode-hook.

Once the mode is active there are several commands available to hide and show macros and environments:

Command: TeX-fold-buffer
(C-c C-o C-b) Hide all macros specified in the variables TeX-fold-macro-spec-list and TeX-fold-env-spec-list. This command can also be used to refresh the whole buffer and hide any new macros and environments which were inserted after the last invocation of the command.

Command: TeX-fold-region
(C-c C-o C-r) Hide all configured macros in the marked region.

Command: TeX-fold-paragraph
(C-c C-o C-p) Hide all configured macros in the paragraph containing point.

Command: TeX-fold-macro
(C-c C-o C-m) Hide the macro on which point currently is located. If the name of the macro is found in TeX-fold-macro-spec-list, the respective display string will be shown instead. If it is not found, the name of the macro in sqare brackets or the default string for unspecified macros (TeX-fold-unspec-macro-display-string) will be shown, depending on the value of the variable TeX-fold-unspec-use-name.

Command: TeX-fold-env
(C-c C-o C-e) Hide the environment on which point currently is located. The behavior regarding the display string is analogous to TeX-fold-macro and determined by the variables TeX-fold-env-spec-list and TeX-fold-unspec-env-display-string respectively.

Command: TeX-fold-clearout-buffer
(C-c C-o b) Permanently unfold all macros and environments in the current buffer.

Command: TeX-fold-clearout-region
(C-c C-o r) Permanently unfold all macros and environments in the marked region.

Command: TeX-fold-clearout-paragraph
(C-c C-o p) Permanently unfold all macros and environments in the paragraph containing point.

Command: TeX-fold-clearout-item
(C-c C-o i) Permanently show the macro or environment on which point currently is located. In contrast to temporarily opening the macro when point is moved sideways onto it, the macro will be permanently unfolded and will not collapse again once point is leaving it.

Command: TeX-fold-dwim
(C-c C-o C-o) Hide or show items according to the current context. If there is folded content, unfold it. If there is a marked region, fold all configured content in this region. If there is no folded content but a macro or environment, fold it.

The commands above will only take macros or environments into consideration which are specified in the variable TeX-fold-macro-spec-list or TeX-fold-env-spec-list respectively.

User Option: TeX-fold-macro-spec-list
List of display strings or argument numbers and macros to fold. If you specify a number, the content of the first mandatory argument of a LaTeX macro will be used as the placeholder.

The placeholder is made by copying the text from the buffer together with its properties, i.e. its face as well. If fontification has not happened when this is done (e.g. because of lazy font locking) the intended fontification will not show up. As a workaround you can leave Emacs idle a few seconds and wait for stealth font locking to finish before you fold the buffer. Or you just re-fold the buffer with TeX-fold-buffer when you notice a wrong fontification.

User Option: TeX-fold-env-spec-list
List of display strings or argument numbers and environments to fold. Argument numbers refer to the \begin' statement. That means if you have e.g. \begin{tabularx}{\linewidth}{XXX} ... \end{tabularx}' and specify 3 as the argument number, the resulting display string will be "XXX".

User Option: TeX-fold-unspec-macro-display-string
Default display string for macros which are not specified in TeX-fold-macro-spec-list.

User Option: TeX-fold-unspec-env-display-string
Default display string for environments which are not specified in TeX-fold-env-spec-list.

User Option: TeX-fold-unspec-use-name
If non-nil the name of the macro or environment surrounded by square brackets is used as display string, otherwise the defaults specified in TeX-fold-unspec-macro-display-string or TeX-fold-unspec-env-display-string respectively.

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

## 6.3 Outlining the Document

AUCTeX supports the standard outline minor mode using LaTeX/ConTeXt sectioning commands as header lines. See section Outline Mode' in GNU Emacs Manual.

You can add your own headings by setting the variable TeX-outline-extra.

Variable: TeX-outline-extra
List of extra TeX outline levels.

Each element is a list with two entries. The first entry is the regular expression matching a header, and the second is the level of the header. A ^' is automatically prepended to the regular expressions in the list, so they must match text at the beginning of the line.

See LaTeX-section-list or ConTeXt-INTERFACE-section-list for existing header levels.

The following example add \item' and \bibliography' headers, with \bibliography' at the same outline level as \section', and \item' being below \subparagraph'.

 (setq TeX-outline-extra '(("[ \t]*\\\\\$$bib\$$?item\\b" 7) ("\\\\bibliography\\b" 2))) 

You may want to check out the unbundled `out-xtra' package for even better outline support. It is available from your favorite emacs lisp archive.

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

This document was generated by XEmacs Webmaster on October, 2 2007 using texi2html