[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 either a fixed string or the content of one of their arguments instead. 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:
(C-c C-o C-b) Hide all foldable items in the current buffer
according to the setting of TeX-fold-type-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.
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.
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
.
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.
(C-c C-o C-r) Hide all configured macros in the marked region.
(C-c C-o C-p) Hide all configured macros in the paragraph containing point.
(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
.
(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.
(C-c C-o C-c) Hide the comment point is located on.
(C-c C-o b) Permanently unfold all macros and environments in the current buffer.
(C-c C-o r) Permanently unfold all macros and environments in the marked region.
(C-c C-o p) Permanently unfold all macros and environments in the paragraph containing point.
(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.
(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.
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.
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”.
Default display string for macros which are not specified in
TeX-fold-macro-spec-list
.
Default display string for environments which are not specified in
TeX-fold-env-spec-list
.
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
.
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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] |
This document was generated by root on January 25, 2013 using texi2html 1.82.