+++ /dev/null
-The main purpose of this package is the extraction of certain
-environments (most notably displayed formulas) from @LaTeX{} sources
-as graphics. This works with @acronym{DVI} files postprocessed by either
-Dvips and Ghostscript or dvipng, but it also works when you are
-using PDF@TeX{} for generating PDF files (usually also postprocessed
-by Ghostscript).
-
-Current uses of the package include the @previewlatex{} package for
-WYSIWYG functionality in the @AUCTeX{} editing environment,
-generation of previews in LyX, as part of the operation of the
-ps4pdf package, the tbook XML system and some other tools.
-
-Producing @acronym{EPS} files with Dvips and its derivatives using the
-@option{-E} option is not a good alternative: People make do by
-fiddling around with @code{\thispagestyle@{empty@}} and hoping for the best
-(namely, that the specified contents will indeed fit on single
-pages), and then trying to guess the baseline of the resulting code
-and stuff, but this is at best dissatisfactory. The preview package
-provides an easy way to ensure that exactly one page per request
-gets shipped, with a well-defined baseline and no page decorations.
-While you still can use the preview package with the `classic'
-
-@example
-dvips -E -i
-@end example
-
-@noindent
-invocation, there are better ways available that don't rely on Dvips
-not getting confused by PostScript specials.
-
-For most applications, you'll want to make use of the @code{tightpage}
-option. This will embed the page dimensions into the PostScript or
-PDF code, obliterating the need to use the @code{-E -i} options to Dvips.
-You can then produce all image files with a single run of
-Ghostscript from a single PDF or PostScript (as opposed to @acronym{EPS})
-file.
-
-Various options exist that will pass @TeX{} dimensions and other
-information about the respective shipped out material (including
-descender size) into the log file, where external applications might
-make use of it.
-
-The possibility for generating a whole set of graphics with a single
-run of Ghostscript (whether from @LaTeX{} or PDF@LaTeX{}) increases
-both speed and robustness of applications. It is also feasible to
-use dvipng on a @acronym{DVI} file with the options
-
-@example
--picky -noghostscript
-@end example
-
-@noindent
-to omit generating any image file that requires Ghostscript, then
-let a script generate all missing files using Dvips/Ghostscript.
-This will usually speed up the process significantly.
-
-@menu
-* Package options::
-* Provided commands::
-@end menu
-
-@node Package options, Provided commands, The LaTeX style file, The LaTeX style file
-@subsection Package options
-The package is included with the customary
-
-@example
-\usepackage[@var{options}]@{preview@}
-@end example
-
-@noindent
-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:
-
-@table @w
-@item @code{active}
-is the most essential option. If this option is not
-specified, the @code{preview} package will be inactive and the document
-will be typeset as if the @code{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
-
-@example
-latex '\PassOptionsToPackage@{active@}@{preview@} \input@{@var{filename}@}'
-@end example
-
-@item @code{noconfig}
-Usually the file @file{prdefault.cfg} gets loaded
-whenever the @code{preview} package gets activated. @file{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
-@code{preview} options like @code{auctex} which have more immediate needs.
-The @code{noconfig} option suppresses loading of those option files,
-too.
-@item @code{psfixbb}
-Dvips determines the bounding boxes from the
-material in the @acronym{DVI} file it understands. Lots of PostScript
-specials are not part of that. Since the @TeX{} boxes do not make
-it into the @acronym{DVI} file, but merely characters, rules and specials
-do, Dvips might include far too small areas. The option @code{psfixbb}
-will include @file{/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.
-@item @code{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.
-@item @code{pdftex}
-If this option is set, PDF@TeX{} is assumed as the
-output driver. This mainly affects the @code{tightpage} option.
-@item @code{xetex}
-If this option is set, Xe@TeX{} is assumed as the
-output driver. This mainly affects the @code{tightpage} option.
-@item @code{displaymath}
-will make all displayed math environments
-subject to preview processing. This will typically be the most
-desired option.
-@item @code{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
-@code{\PreviewSnarfEnvironment} command on the floats you want to
-have previewed.
-@item @code{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 @code{\(}, @code{\)}
-and @code{$} and the @code{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.
-@item @code{graphics}
-will subject all @code{\includegraphics} commands
-to a preview.
-@item @code{sections}
-will subject all section headers to a preview.
-@item @code{delayed}
-will delay all activations and redefinitions the
-@code{preview} package makes until @code{\}@code{begin@{document@}}. The purpose
-of this is to cater for documents which should be subjected to the
-@code{preview} package without having been prepared for it. You can
-process such documents with
-
-@example
-latex '\RequirePackage[active,delayed,@var{options}]@{preview@}
-\input@{@var{filename}@}'
-@end example
-
-@noindent
-This relaxes the requirement to be loading the @code{preview} package
-as last package.
-@item @var{driver}
-loads a special driver file
-@file{pr@var{driver}.def}. The remaining options are implemented
-through the use of driver files.
-@item @code{auctex}
-This driver will produce fake error messages at the
-start and end of every preview environment that enable the Emacs
-package @previewlatex{} 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 @emph{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 @code{\PassOptionsToPackage} in
-order to effect the desired behaviour. In addition,
-@file{prauctex.cfg} will get loaded unless inhibited by the @code{noconfig}
-option. This caters for the most frequently encountered
-problematic commands.
-@item @code{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
-@previewlatex{}, I'd strongly recommend that you check out the
-Ref@TeX{} package which pretty much obliterates the need for this
-kind of functionality. If you still want it, standard @LaTeX{}
-provides it with the @code{showkeys} package, and there is also the
-less encompassing @code{showlabels} package. Unfortunately, since
-those go to some pain not to change the page layout and spacing,
-they also don't change @code{preview}'s idea of the @TeX{} dimensions of
-the involved boxes. So if you are using @code{preview} for determing
-bounding boxes, those packages are mostly useless. The option
-@code{showlabels} offers a substitute for them.
-@item @code{tightpage}
-It is not uncommon to want to use the results of
-@code{preview} as graphic images for some other application. One
-possibility is to generate a flurry of @acronym{EPS} files with
-
-@example
-dvips -E -i -Pwww -o @var{outputfile}.000 @var{inputfile}
-@end example
-
-@noindent
-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 @acronym{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@w{ }@emph{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 @code{tightpage} option. That way a single
-command line like
-
-@example
-@option{gs -sDEVICE=png16m -dTextAlphaBits=4 -r300
--dGraphicsAlphaBits=4 -dSAFER -q -dNOPAUSE
--sOutputFile=@var{outputfile}%d.png @var{inputfile}.ps}
-@end example
-
-@noindent
-will be able to produce tight graphics from a single PostScript
-file generated with Dvips @emph{without} use of the options
-@code{-E -i}, in a single run.
-
-The @code{tightpage} option actually also works when using the @code{pdftex}
-option and generating PDF files with PDF@TeX{}. 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 @code{dvips} or @code{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 @code{preview}'s automatic extraction facilities, no problem: just
-don't use any of the extraction options, and wrap everything to be
-previewed into @code{preview} environments. This is how LyX does its
-math previews.
-
-If the pages under the @code{tightpage} option are just too tight, you
-can adjust by setting the length @code{\PreviewBorder} to a different
-value by using @code{\setlength}. The default value is
-@file{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 @code{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 @code{\PreviewBbAdjust} with the
-help of @code{\renewcommand}. Its default value is
-
-@example
-\newcommand \PreviewBbAdjust
-@{-\PreviewBorder -\PreviewBorder
-\PreviewBorder \PreviewBorder@}
-@end example
-
-@noindent
-This adjusts the left, lower, right and upper borders by the given
-amount. The macro must contain 4@w{ }@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@w{ }@code{bp}.
-@item @code{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).
-@item @code{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 @code{@{@}} braces, followed by a space. The last such pair is
-followed by a colon (@code{:}) if it is at the start of the preview
-snippet, and by a period (@file{.}) 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 @previewlatex{} use this for keeping counters accurate
-when single previews are regenerated.
-@item @code{footnotes}
-This makes footnotes render as previews, and only
-as their footnote symbol. A convenient editing feature inside of
-Emacs.
-@end table
-
-The following options are just for debugging purposes of the package
-and similar to the corresponding @TeX{} commands they allude to:
-
-@table @w
-@item @code{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 @code{\errorstopmode}, nor will it change the
-setting of @code{\tracingonline}.
-@item @code{showbox}
-This option will show the contents of the boxes
-shipped out to the @acronym{DVI} files. It also sets @code{\showboxbreadth} and
-@code{\showboxdepth} to their maximum values at the end of loading this
-package, but you may reset them if you don't like that.
-@end table
-
-@node Provided commands, ,Package options, The LaTeX style file
-@subsection Provided commands
-
-@table @code
-@item \begin@{preview@}@dots{}\end@{preview@}
-The @code{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 @code{preview} package has not
-been activated, the contents of this environment will be typeset
-normally.
-
-@item \begin@{nopreview@}@dots{}\end@{nopreview@}
-The @code{nopreview} environment will cause its
-contents not to undergo any special treatment by the @code{preview}
-package. When @code{preview} is active, the contents will be discarded
-like all main text that does not trigger the @code{preview} hooks. When
-@code{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 @code{\ifPreview} conditional for it.
-
-@item \PreviewMacro
-If you want to make a macro like
-@findex \PreviewMacro
-@code{\includegraphics} (actually, this is what is done by the
-@code{graphics} option to @code{preview}) produce a preview image, you put a
-declaration like
-
-@example
-\PreviewMacro[*[[!]@{\includegraphics@}
-@end example
-
-@noindent
-or, more readable,
-
-@example
-\PreviewMacro[@{*[][]@{@}@}]@{\includegraphics@}
-@end example
-
-@noindent
-into your preamble. The optional argument to @code{\PreviewMacro}
-specifies the arguments @code{\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 @code{[@{} and @code{@}]} pair. The inner braces are
-necessary to stop any included @code{[]} pairs from prematurely ending
-the optional argument, and to make a single @code{@{@}}
-denoting an optional argument not get stripped away by @TeX{}'s
-argument parsing.
-
-The letters simply mean
-
-@table @w
-@item @code{*}
-indicates an optional @code{*} modifier, as in
-@code{\includegraphics*}.
-@item @code{[}
-^^A]
-indicates an optional argument in brackets. This syntax
-is somewhat baroque, but brief.
-@item @code{[]}
-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.
-@item @code{!}
-indicates a mandatory argument.
-@item @code{@{@}}
-indicates the same. Again, be sure to have
-that additional level of braces around the whole argument
-specification.
-@item @code{?}@var{delimiter}@{@var{true case}@}@{@var{false case}@}
-is a
-conditional. The next character is checked against being equal to
-@var{delimiter}. If it is, the specification @var{true case} is
-used for the further parsing, otherwise @var{false case} will be
-employed. In neither case is something consumed from the input,
-so @{@var{true case}@} will still have to deal with the upcoming
-delimiter.
-@item @code{@@}@{@var{literal sequence}@}
-will insert the given sequence
-literally into the executed call of the command.
-@item @code{-}
-will just drop the next token. It will probably be most
-often used in the true branch of a @code{?} specification.
-@item @code{#}@{@var{argument}@}@{@var{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 @code{[]} option could manually
-be implemented with the option string @code{?[@{#@{[#1]@}@{[@{#1@}]@}@}@{@}}.
-PStricks users might enjoy this sort of flexibility.
-@item @code{:}@{@var{argument}@}@{@var{replacement}@}
-is again a
-transformation rule. As opposed to @code{#}, however, the result of
-the transformation is parsed again. You'll rarely need this.
-@end table
-
-
-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 @code{#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@w{ }@code{[#1]}.
-
-@item \PreviewMacro*
-A similar invocation
-@code{\PreviewMacro*} simply throws the macro and all of its
-arguments declared in the manner above away. This is mostly useful
-for having things like @code{\footnote} not do their magic on their
-arguments. More often than not, you don't want to declare any
-arguments to scan to @code{\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 @code{\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 @code{#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@w{ }@code{[]} since the command usually gets thrown
-away.
-
-As an example for using this argument, you might want to specify
-
-@example
-\PreviewMacro*\footnote[@{[]@}][#1@{@}]
-@end example
-
-@noindent
-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 @previewlatex{}.
-
-@item \PreviewEnvironment
-The macro
-@findex \PreviewEnvironment
-@code{\PreviewEnvironment} works just as @code{\PreviewMacro} does,
-only for environments. @item \PreviewEnvironment*
-And the
-same goes for @code{\PreviewEnvironment*} as compared to
-@code{\PreviewMacro*}.
-
-@item \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
-
-@enumerate
-@item produce insertion material that cannot be extracted to the
-preview properly,
-@item complain with an error message about not being in outer par
-mode.
-@end enumerate
-
-
-@item \PreviewOpen
-@item \PreviewClose
-Those Macros form a matched preview pair. This is for macros that
-behave similar as @code{\begin} and @code{\end} of an environment. It
-is essential for the operation of @code{\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 @code{nopreview}
-environment. Similarly, the macro treated with @code{PreviewClose}
-will close an environment even when inactive.
-
-@item \ifPreview
-In case you need to know whether
-@code{preview} is active, you can use the conditional @code{\ifPreview}
-together with @code{\else} and @code{\fi}.
-
-@end table