[ < ] [ > ]   [ << ] [ 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] [ ? ]

This document was generated by Build Daemon user on April, 24 2005 using texi2html