preview-latex: Package options
6.1.1 Package options
---------------------
The package is included with the customary
\usepackage[OPTIONS]{preview}
You should usually load this package as the last one, since it redefines
several things that other packages may also provide.
The following options are available:
'active'
is the most essential option. If this option is not specified, the
'preview' package will be inactive and the document will be typeset
as if the 'preview' package were not loaded, except that all
declarations and environments defined by the package are still
legal but have no effect. This allows defining previewing
characteristics in your document, and only activating them by
calling LaTeX as
latex '\PassOptionsToPackage{active}{preview} \input{FILENAME}'
'noconfig'
Usually the file 'prdefault.cfg' gets loaded whenever the 'preview'
package gets activated. 'prdefault.cfg' is supposed to contain
definitions that can cater for otherwise bad results, for example,
if a certain document class would otherwise lead to trouble. It
also can be used to override any settings made in this package,
since it is loaded at the very end of it. In addition, there may
be configuration files specific for certain 'preview' options like
'auctex' which have more immediate needs. The 'noconfig' option
suppresses loading of those option files, too.
'psfixbb'
Dvips determines the bounding boxes from the material in the DVI
file it understands. Lots of PostScript specials are not part of
that. Since the TeX boxes do not make it into the DVI file, but
merely characters, rules and specials do, Dvips might include far
too small areas. The option 'psfixbb' will include '/dev/null' as
a graphic file in the ultimate upper left and lower right corner of
the previewed box. This will make Dvips generate an appropriate
bounding box.
'dvips'
If this option is specified as a class option or to other packages,
several packages pass things like page size information to Dvips,
or cause crop marks or draft messages written on pages. This
seriously hampers the usability of previews. If this option is
specified, the changes will be undone if possible.
'pdftex'
If this option is set, PDFTeX is assumed as the output driver.
This mainly affects the 'tightpage' option.
'xetex'
If this option is set, XeTeX is assumed as the output driver. This
mainly affects the 'tightpage' option.
'displaymath'
will make all displayed math environments subject to preview
processing. This will typically be the most desired option.
'floats'
will make all float objects subject to preview processing. If you
want to be more selective about what floats to pass through to a
preview, you should instead use the '\PreviewSnarfEnvironment'
command on the floats you want to have previewed.
'textmath'
will make all text math subject to previews. Since math mode is
used throughly inside of LaTeX even for other purposes, this works
by redefining '\(', '\)' and '$' and the 'math' environment
(apparently some people use that). Only occurences of these text
math delimiters in later loaded packages and in the main document
will thus be affected.
'graphics'
will subject all '\includegraphics' commands to a preview.
'sections'
will subject all section headers to a preview.
'delayed'
will delay all activations and redefinitions the 'preview' package
makes until '\''begin{document}'. The purpose of this is to cater
for documents which should be subjected to the 'preview' package
without having been prepared for it. You can process such
documents with
latex '\RequirePackage[active,delayed,OPTIONS]{preview}
\input{FILENAME}'
This relaxes the requirement to be loading the 'preview' package as
last package.
DRIVER
loads a special driver file 'prDRIVER.def'. The remaining options
are implemented through the use of driver files.
'auctex'
This driver will produce fake error messages at the start and end
of every preview environment that enable the Emacs package
preview-latex in connection with AUCTeX to pinpoint the exact
source location where the previews have originated. Unfortunately,
there is no other reliable means of passing the current TeX input
position _in_ a line to external programs. In order to make the
parsing more robust, this option also switches off quite a few
diagnostics that could be misinterpreted.
You should not specify this option manually, since it will only be
needed by automated runs that want to parse the pseudo error
messages. Those runs will then use '\PassOptionsToPackage' in
order to effect the desired behaviour. In addition, 'prauctex.cfg'
will get loaded unless inhibited by the 'noconfig' option. This
caters for the most frequently encountered problematic commands.
'showlabels'
During the editing process, some people like to see the label names
in their equations, figures and the like. Now if you are using
Emacs for editing, and in particular preview-latex, I'd strongly
recommend that you check out the RefTeX package which pretty much
obliterates the need for this kind of functionality. If you still
want it, standard LaTeX provides it with the 'showkeys' package,
and there is also the less encompassing 'showlabels' package.
Unfortunately, since those go to some pain not to change the page
layout and spacing, they also don't change 'preview''s idea of the
TeX dimensions of the involved boxes. So if you are using
'preview' for determing bounding boxes, those packages are mostly
useless. The option 'showlabels' offers a substitute for them.
'tightpage'
It is not uncommon to want to use the results of 'preview' as
graphic images for some other application. One possibility is to
generate a flurry of EPS files with
dvips -E -i -Pwww -o OUTPUTFILE.000 INPUTFILE
However, in case those are to be processed further into graphic
image files by Ghostscript, this process is inefficient since all
of those files need to be processed one by one. In addition, it is
necessary to extract the bounding box comments from the EPS files
and convert them into page dimension parameters for Ghostscript in
order to avoid full-page graphics. This is not even possible if
you wanted to use Ghostscript in a _single_ run for generating the
files from a single PostScript file, since Dvips will in that case
leave no bounding box information anywhere.
The solution is to use the 'tightpage' option. That way a single
command line like
gs -sDEVICE=png16m -dTextAlphaBits=4 -r300
-dGraphicsAlphaBits=4 -dSAFER -q -dNOPAUSE
-sOutputFile=OUTPUTFILE%d.png INPUTFILE.ps
will be able to produce tight graphics from a single PostScript
file generated with Dvips _without_ use of the options '-E -i', in
a single run.
The 'tightpage' option actually also works when using the 'pdftex'
option and generating PDF files with PDFTeX. The resulting PDF
file has separate page dimensions for every page and can directly
be converted with one run of Ghostscript into image files.
If neither 'dvips' or 'pdftex' have been specified, the
corresponding option will get autodetected and invoked.
If you need this in a batch environment where you don't want to use
'preview''s automatic extraction facilities, no problem: just don't
use any of the extraction options, and wrap everything to be
previewed into 'preview' environments. This is how LyX does its
math previews.
If the pages under the 'tightpage' option are just too tight, you
can adjust by setting the length '\PreviewBorder' to a different
value by using '\setlength'. The default value is '0.50001bp',
which is half of a usual PostScript point, rounded up. If you go
below this value, the resulting page size may drop below '1bp', and
Ghostscript does not seem to like that. If you need finer control,
you can adjust the bounding box dimensions individually by changing
the macro '\PreviewBbAdjust' with the help of '\renewcommand'. Its
default value is
\newcommand \PreviewBbAdjust
{-\PreviewBorder -\PreviewBorder
\PreviewBorder \PreviewBorder}
This adjusts the left, lower, right and upper borders by the given
amount. The macro must contain 4 TeX dimensions after another, and
you may not omit the units if you specify them explicitly instead
of by register. PostScript points have the unit 'bp'.
'lyx'
This option is for the sake of LyX developers. It will output a
few diagnostics relevant for the sake of LyX' preview functionality
(at the time of writing, mostly implemented for math insets, in
versions of LyX starting with 1.3.0).
'counters'
This writes out diagnostics at the start and the end of previews.
Only the counters changed since the last output get written, and if
no counters changed, nothing gets written at all. The list
consists of counter name and value, both enclosed in '{}' braces,
followed by a space. The last such pair is followed by a colon
(':') if it is at the start of the preview snippet, and by a period
('.') if it is at the end. The order of different diagnostics like
this being issued depends on the order of the specification of the
options when calling the package.
Systems like preview-latex use this for keeping counters accurate
when single previews are regenerated.
'footnotes'
This makes footnotes render as previews, and only as their footnote
symbol. A convenient editing feature inside of Emacs.
The following options are just for debugging purposes of the package
and similar to the corresponding TeX commands they allude to:
'tracingall'
causes lots of diagnostic output to appear in the log file during
the preview collecting phases of TeX's operation. In contrast to
the similarly named TeX command, it will not switch to
'\errorstopmode', nor will it change the setting of
'\tracingonline'.
'showbox'
This option will show the contents of the boxes shipped out to the
DVI files. It also sets '\showboxbreadth' and '\showboxdepth' to
their maximum values at the end of loading this package, but you
may reset them if you don't like that.
Info Catalog
preview-latex: The LaTeX style file
preview-latex: The LaTeX style file
preview-latex: Provided commands