preview-latex: Provided commands
6.1.2 Provided commands
-----------------------
'\begin{preview}...\end{preview}'
The 'preview' environment causes its contents to be set as a single
preview image. Insertions like figures and footnotes (except those
included in minipages) will typically lead to error messages or be
lost. In case the 'preview' package has not been activated, the
contents of this environment will be typeset normally.
'\begin{nopreview}...\end{nopreview}'
The 'nopreview' environment will cause its contents not to undergo
any special treatment by the 'preview' package. When 'preview' is
active, the contents will be discarded like all main text that does
not trigger the 'preview' hooks. When 'preview' is not active, the
contents will be typeset just like the main text.
Note that both of these environments typeset things as usual when
preview is not active. If you need something typeset
conditionally, use the '\ifPreview' conditional for it.
'\PreviewMacro'
If you want to make a macro like '\includegraphics' (actually, this
is what is done by the 'graphics' option to 'preview') produce a
preview image, you put a declaration like
\PreviewMacro[*[[!]{\includegraphics}
or, more readable,
\PreviewMacro[{*[][]{}}]{\includegraphics}
into your preamble. The optional argument to '\PreviewMacro'
specifies the arguments '\includegraphics' accepts, since this is
necessary information for properly ending the preview box. Note
that if you are using the more readable form, you have to enclose
the argument in a '[{' and '}]' pair. The inner braces are
necessary to stop any included '[]' pairs from prematurely ending
the optional argument, and to make a single '{}' denoting an
optional argument not get stripped away by TeX's argument parsing.
The letters simply mean
'*'
indicates an optional '*' modifier, as in '\includegraphics*'.
'['
^^A] indicates an optional argument in brackets. This syntax
is somewhat baroque, but brief.
'[]'
also indicates an optional argument in brackets. Be sure to
have encluded the entire optional argument specification in an
additional pair of braces as described above.
'!'
indicates a mandatory argument.
'{}'
indicates the same. Again, be sure to have that additional
level of braces around the whole argument specification.
'?'DELIMITER{TRUE CASE}{FALSE CASE}
is a conditional. The next character is checked against being
equal to DELIMITER. If it is, the specification TRUE CASE is
used for the further parsing, otherwise FALSE CASE will be
employed. In neither case is something consumed from the
input, so {TRUE CASE} will still have to deal with the
upcoming delimiter.
'@'{LITERAL SEQUENCE}
will insert the given sequence literally into the executed
call of the command.
'-'
will just drop the next token. It will probably be most often
used in the true branch of a '?' specification.
'#'{ARGUMENT}{REPLACEMENT}
is a transformation rule that calls a macro with the given
argument and replacement text on the rest of the argument
list. The replacement is used in the executed call of the
command. This can be used for parsing arbitrary constructs.
For example, the '[]' option could manually be implemented
with the option string '?[{#{[#1]}{[{#1}]}}{}'. PStricks
users might enjoy this sort of flexibility.
':'{ARGUMENT}{REPLACEMENT}
is again a transformation rule. As opposed to '#', however,
the result of the transformation is parsed again. You'll
rarely need this.
There is a second optional argument in brackets that can be used to
declare any default action to be taken instead. This is mostly for
the sake of macros that influence numbering: you would want to keep
their effects in that respect. The default action should use '#1'
for referring to the original (not the patched) command with the
parsed options appended. Not specifying a second optional argument
here is equivalent to specifying '[#1]'.
'\PreviewMacro*'
A similar invocation '\PreviewMacro*' simply throws the macro and
all of its arguments declared in the manner above away. This is
mostly useful for having things like '\footnote' not do their magic
on their arguments. More often than not, you don't want to declare
any arguments to scan to '\PreviewMacro*' since you would want the
remaining arguments to be treated as usual text and typeset in that
manner instead of being thrown away. An exception might be, say,
sort keys for '\cite'.
A second optional argument in brackets can be used to declare any
default action to be taken instead. This is for the sake of macros
that influence numbering: you would want to keep their effects in
that respect. The default action might use '#1' for referring to
the original (not the patched) command with the parsed options
appended. Not specifying a second optional argument here is
equivalent to specifying '[]' since the command usually gets thrown
away.
As an example for using this argument, you might want to specify
\PreviewMacro*[{[]}][#1{}]{\footnote}
This will replace a footnote by an empty footnote, but taking any
optional parameter into account, since an optional paramter changes
the numbering scheme. That way the real argument for the footnote
remains for processing by preview-latex.
'\PreviewEnvironment'
The macro '\PreviewEnvironment' works just as '\PreviewMacro' does,
only for environments.
'\PreviewEnvironment*'
And the same goes for '\PreviewEnvironment*' as compared to
'\PreviewMacro*'.
'\PreviewSnarfEnvironment'
This macro does not typeset the original environment inside of a
preview box, but instead typesets just the contents of the original
environment inside of the preview box, leaving nothing for the
original environment. This has to be used for figures, for
example, since they would
1. produce insertion material that cannot be extracted to the
preview properly,
2. complain with an error message about not being in outer par
mode.
'\PreviewOpen'
'\PreviewClose'
Those Macros form a matched preview pair. This is for macros that
behave similar as '\begin' and '\end' of an environment. It is
essential for the operation of '\PreviewOpen' that the macro
treated with it will open an additional group even when the preview
falls inside of another preview or inside of a 'nopreview'
environment. Similarly, the macro treated with '\PreviewClose'
will close an environment even when inactive.
'\ifPreview'
In case you need to know whether 'preview' is active, you can use
the conditional '\ifPreview' together with '\else' and '\fi'.
Info Catalog
preview-latex: Package options
preview-latex: The LaTeX style file