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*.

[

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*\footnote[{[]}][#1{}]
     

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 (the actual definition is more complicated in order not to change the numbering in case of optional arguments being present).

\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.