auctex: Folding
3.2 Folding Macros and Environments
===================================
A popular complaint about markup languages like TeX and LaTeX is that
there is too much clutter in the source text and that one cannot focus
well on the content. There are macros where you are only interested in
the content they are enclosing, like font specifiers where the content
might already be fontified in a special way by font locking. Or macros
the content of which you only want to see when actually editing it, like
footnotes or citations. Similarly you might find certain environments
or comments distracting when trying to concentrate on the body of your
document.
With AUCTeX's folding functionality you can collapse those items and
replace them by a fixed string, the content of one of their arguments,
or a mixture of both. If you want to make the original text visible
again 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 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, environments and comments:
-- Command: TeX-fold-buffer
('C-c C-o C-b') Hide all foldable items in the current buffer
according to the setting of 'TeX-fold-type-list'.
If you want to have this done automatically every time you open a
file, add it to a hook and make sure the function is called after
font locking is set up for the buffer. The following code should
accomplish this:
(add-hook 'find-file-hook 'TeX-fold-buffer t)
The command can be used any time to refresh the whole buffer and
fold any new macros and environments which were inserted after the
last invocation of the command.
-- User Option: TeX-fold-type-list
List of symbols determining the item classes to consider for
folding. This can be macros, environments and comments. Per
default only macros and environments are folded.
-- User Option: TeX-fold-force-fontify
In order for all folded content to get the right faces, the whole
buffer has to be fontified before folding is carried out.
'TeX-fold-buffer' therefore will force fontification of unfontified
regions. As this will prolong the time folding takes, you can
prevent forced fontification by customizing the variable
'TeX-fold-force-fontify'.
-- User Option: TeX-fold-auto
By default, a macro inserted with 'TeX-insert-macro' ('C-c C-m')
will not be folded. Set this variable to a non-nil value to
aumatically fold macros as soon as they are inserted.
-- User Option: TeX-fold-preserve-comments
By default items found in comments will be folded. If your
comments often contain unfinished code this might lead to problems.
Give this variable a non-nil value and foldable items in your
comments will be left alone.
-- User Option: TeX-fold-unfold-around-mark
When this variable is non-nil and there is an active regione, text
around the mark will be kept unfolded.
-- 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-math
Hide the math macro on which point currently is located. If the
name of the macro is found in 'TeX-fold-math-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-comment
('C-c C-o C-c') Hide the comment point is located on.
-- 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.
In case you want to use a different prefix than 'C-c C-o' for these
commands you can customize the variable 'TeX-fold-command-prefix'.
(Note that this will not change the key binding for activating the
mode.)
The commands above will only take macros or environments into
consideration which are specified in the variables
'TeX-fold-macro-spec-list' or 'TeX-fold-env-spec-list' respectively.
-- User Option: TeX-fold-macro-spec-list
List of replacement specifiers and macros to fold. The specifier
can be a string, an integer or a function symbol.
If you specify a string, it will be used as a display replacement
for the whole macro. Numbers in braces, brackets, parens or angle
brackets will be replaced by the respective macro argument. For
example '{1}' will be replaced by the first mandatory argument of
the macro. One can also define alternatives within the specifier
which are used if an argument is not found. Alternatives are
separated by '||'. They are most useful with optional arguments.
As an example, the default specifier for '\item' is '[1]:||*' which
means that if there is an optional argument, its value is shown
followed by a colon. If there is no optional argument, only an
asterisk is used as the display string.
If you specify a number as the first element, the content of the
respective mandatory argument of a LaTeX macro will be used as the
placeholder.
If the first element is a function symbol, the function will be
called with all mandatory arguments of the macro and the result of
the function call will be used as a replacement for the macro.
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-math-spec-list
List of display strings and math macros to fold.
The variables 'TeX-fold-macro-spec-list', 'TeX-fold-env-spec-list',
and 'TeX-fold-math-spec-list' apply to any AUCTeX mode. If you want to
make settings which are only applied to LaTeX mode, you can use the
mode-specific variables 'LaTeX-fold-macro-spec-list',
'LaTeX-fold-env-spec-list', and 'LaTeX-fold-math-spec-list'
-- 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.
When you hover with the mouse pointer over folded content, its
original text will be shown in a tooltip or the echo area depending on
Tooltip mode being activate. In order to avoid exorbitantly big
tooltips and to cater for the limited space in the echo area the content
will be cropped after a certain amount of characters defined by the
variable 'TeX-fold-help-echo-max-length'.
-- User Option: TeX-fold-help-echo-max-length
Maximum length of original text displayed in a tooltip or the echo
area for folded content. Set it to zero in order to disable this
feature.
Info Catalog
auctex: Font Locking
auctex: Display
auctex: Outline