auctex: Fontification of macros
3.1.1 Fontification of macros
-----------------------------
Highlighting of macros can be customized by adapting keyword lists which
can be found in the customization group 'font-latex-keywords'.
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.
Customization variables for '\foo[bar]{baz}' type macros allow both
the macro name and the sequence of arguments to be specified. The
latter is done with a string which can contain the characters
'*'
indicating the existence of a starred variant for the macro,
'['
for optional arguments in brackets,
'{'
for mandatory arguments in braces,
'\'
for mandatory arguments consisting of a single macro and
'|'
as a prefix indicating that two alternatives are following.
For example the specifier for '\documentclass' would be '[{' because
the macro has one optional followed by one mandatory argument. The
specifier for '\newcommand' would be '*|{\[[{' because there is a
starred variant, the mandatory argument following the macro name can be
a macro or a TeX group which can be followed by two optional arguments
and the last token is a mandatory argument in braces.
Customization variables for the '{\foo text}' and '\foo' types are
simple lists of strings where each entry is a macro name (without the
leading backslash).
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-constant-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-fontify-sectioning'.
-- User Option: font-latex-fontify-sectioning
Per default sectioning commands will be shown in a larger,
proportional font, which corresponds to a number for this variable.
The font size varies with the sectioning level, e.g. '\part'
('font-latex-sectioning-0-face') has a larger font than
'\paragraph' ('font-latex-sectioning-5-face'). Typically, values
from 1.05 to 1.3 for 'font-latex-fontify-sectioning' give best
results, depending on your font setup. If you rather like to use
the base font and a different color, set the variable to the symbol
'color'. In this case the face 'font-lock-type-face' will be used
to fontify the argument of the sectioning commands.
You can make font-latex aware of your own sectioning commands be
adding them to the keyword lists:
'font-latex-match-sectioning-0-keywords'
('font-latex-sectioning-0-face') ...
'font-latex-match-sectioning-5-keywords'
('font-latex-sectioning-5-face').
Related to sectioning there is special support for slide titles which
may be fontified with the face 'font-latex-slide-title-face'. You can
add macros which should appear in this face by customizing the variable
'font-latex-match-slide-title-keywords'.
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'
Deactivating defaults of built-in keyword classes
-------------------------------------------------
font-latex ships with predefined lists of keywords for the classes
described above. You can disable these defaults per class by
customizing the variable 'font-latex-deactivated-keyword-classes'. This
is a list of strings for keyword classes to be deactivated. Valid
entries are "warning", "variable", "biblatexnoarg", "biblatex",
"reference", "function" , "sectioning-0", "sectioning-1",
"sectioning-2", "sectioning-3", "sectioning-4", "sectioning-5",
"slide-title", "textual", "bold-command", "italic-command",
"math-command", "type-command", "bold-declaration",
"italic-declaration", "type-declaration".
You can also get rid of certain keywords only. For example if you
want to remove highlighting of footnotes as references you can put the
following stanza into your init file:
(eval-after-load "font-latex"
'(setq-default
font-latex-match-reference-keywords-local
(remove (TeX-assoc-string "footnote"
font-latex-match-reference-keywords-local)
font-latex-match-reference-keywords-local)))
But note that this means fiddling with font-latex's internals and is
not guaranteed to work in future versions of font-latex.
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 list of keywords defines which commands and declarations should
be covered by the keyword class. A keyword can either be a simple
command name omitting the leading backslash or a list consisting of
the command name and a string specifying the sequence of arguments
for the command.
The face argument can either be an existing face or face attributes
made by you.
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.