1 The main purpose of this package is the extraction of certain
2 environments (most notably displayed formulas) from @LaTeX{} sources
3 as graphics. This works with @acronym{DVI} files postprocessed by either
4 Dvips and Ghostscript or dvipng, but it also works when you are
5 using PDF@TeX{} for generating PDF files (usually also postprocessed
8 Current uses of the package include the @previewlatex{} package for
9 WYSIWYG functionality in the @AUCTeX{} editing environment,
10 generation of previews in LyX, as part of the operation of the
11 pst-pdf package, the tbook XML system and some other tools.
13 Producing @acronym{EPS} files with Dvips and its derivatives using the
14 @option{-E} option is not a good alternative: People make do by
15 fiddling around with @code{\thispagestyle@{empty@}} and hoping for the best
16 (namely, that the specified contents will indeed fit on single
17 pages), and then trying to guess the baseline of the resulting code
18 and stuff, but this is at best dissatisfactory. The preview package
19 provides an easy way to ensure that exactly one page per request
20 gets shipped, with a well-defined baseline and no page decorations.
21 While you still can use the preview package with the `classic'
28 invocation, there are better ways available that don't rely on Dvips
29 not getting confused by PostScript specials.
31 For most applications, you'll want to make use of the @code{tightpage}
32 option. This will embed the page dimensions into the PostScript or
33 PDF code, obliterating the need to use the @code{-E -i} options to Dvips.
34 You can then produce all image files with a single run of
35 Ghostscript from a single PDF or PostScript (as opposed to @acronym{EPS})
38 Various options exist that will pass @TeX{} dimensions and other
39 information about the respective shipped out material (including
40 descender size) into the log file, where external applications might
43 The possibility for generating a whole set of graphics with a single
44 run of Ghostscript (whether from @LaTeX{} or PDF@LaTeX{}) increases
45 both speed and robustness of applications. It is also feasible to
46 use dvipng on a @acronym{DVI} file with the options
53 to omit generating any image file that requires Ghostscript, then
54 let a script generate all missing files using Dvips/Ghostscript.
55 This will usually speed up the process significantly.
62 @node Package options, Provided commands, The LaTeX style file, The LaTeX style file
63 @subsection Package options
64 The package is included with the customary
67 \usepackage[@var{options}]@{preview@}
71 You should usually load this package as the last one, since it
72 redefines several things that other packages may also provide.
74 The following options are available:
78 is the most essential option. If this option is not
79 specified, the @code{preview} package will be inactive and the document
80 will be typeset as if the @code{preview} package were not loaded,
81 except that all declarations and environments defined by the
82 package are still legal but have no effect. This allows defining
83 previewing characteristics in your document, and only activating
84 them by calling @LaTeX{} as
87 latex '\PassOptionsToPackage@{active@}@{preview@} \input@{@var{filename}@}'
91 Usually the file @file{prdefault.cfg} gets loaded
92 whenever the @code{preview} package gets activated. @file{prdefault.cfg} is
93 supposed to contain definitions that can cater for otherwise bad
94 results, for example, if a certain document class would otherwise
95 lead to trouble. It also can be used to override any settings
96 made in this package, since it is loaded at the very end of it.
97 In addition, there may be configuration files specific for certain
98 @code{preview} options like @code{auctex} which have more immediate needs.
99 The @code{noconfig} option suppresses loading of those option files,
102 Dvips determines the bounding boxes from the
103 material in the @acronym{DVI} file it understands. Lots of PostScript
104 specials are not part of that. Since the @TeX{} boxes do not make
105 it into the @acronym{DVI} file, but merely characters, rules and specials
106 do, Dvips might include far too small areas. The option @code{psfixbb}
107 will include @file{/dev/null} as a graphic file in the ultimate upper
108 left and lower right corner of the previewed box. This will make
109 Dvips generate an appropriate bounding box.
111 If this option is specified as a class option or to
112 other packages, several packages pass things like page size
113 information to Dvips, or cause crop marks or draft messages
114 written on pages. This seriously hampers the usability of
115 previews. If this option is specified, the changes will be undone
118 If this option is set, PDF@TeX{} is assumed as the
119 output driver. This mainly affects the @code{tightpage} option.
121 If this option is set, Xe@TeX{} is assumed as the
122 output driver. This mainly affects the @code{tightpage} option.
123 @item @code{displaymath}
124 will make all displayed math environments
125 subject to preview processing. This will typically be the most
128 will make all float objects subject to preview
129 processing. If you want to be more selective about what floats to
130 pass through to a preview, you should instead use the
131 @code{\PreviewSnarfEnvironment} command on the floats you want to
133 @item @code{textmath}
134 will make all text math subject to previews.
135 Since math mode is used throughly inside of @LaTeX{} even for other
136 purposes, this works by redefining @code{\(}, @code{\)}
137 and @code{$} and the @code{math} environment (apparently some people use
138 that). Only occurences of these text math delimiters in later
139 loaded packages and in the main document will thus be affected.
140 @item @code{graphics}
141 will subject all @code{\includegraphics} commands
143 @item @code{sections}
144 will subject all section headers to a preview.
146 will delay all activations and redefinitions the
147 @code{preview} package makes until @code{\}@code{begin@{document@}}. The purpose
148 of this is to cater for documents which should be subjected to the
149 @code{preview} package without having been prepared for it. You can
150 process such documents with
153 latex '\RequirePackage[active,delayed,@var{options}]@{preview@}
154 \input@{@var{filename}@}'
158 This relaxes the requirement to be loading the @code{preview} package
161 loads a special driver file
162 @file{pr@var{driver}.def}. The remaining options are implemented
163 through the use of driver files.
165 This driver will produce fake error messages at the
166 start and end of every preview environment that enable the Emacs
167 package @previewlatex{} in connection with @AUCTeX{} to pinpoint
168 the exact source location where the previews have originated.
169 Unfortunately, there is no other reliable means of passing the
170 current @TeX{} input position @emph{in} a line to external
171 programs. In order to make the parsing more robust, this option
172 also switches off quite a few diagnostics that could be
175 You should not specify this option manually, since it will only be
176 needed by automated runs that want to parse the pseudo error
177 messages. Those runs will then use @code{\PassOptionsToPackage} in
178 order to effect the desired behaviour. In addition,
179 @file{prauctex.cfg} will get loaded unless inhibited by the @code{noconfig}
180 option. This caters for the most frequently encountered
181 problematic commands.
182 @item @code{showlabels}
183 During the editing process, some people like to
184 see the label names in their equations, figures and the like. Now
185 if you are using Emacs for editing, and in particular
186 @previewlatex{}, I'd strongly recommend that you check out the
187 Ref@TeX{} package which pretty much obliterates the need for this
188 kind of functionality. If you still want it, standard @LaTeX{}
189 provides it with the @code{showkeys} package, and there is also the
190 less encompassing @code{showlabels} package. Unfortunately, since
191 those go to some pain not to change the page layout and spacing,
192 they also don't change @code{preview}'s idea of the @TeX{} dimensions of
193 the involved boxes. So if you are using @code{preview} for determing
194 bounding boxes, those packages are mostly useless. The option
195 @code{showlabels} offers a substitute for them.
196 @item @code{tightpage}
197 It is not uncommon to want to use the results of
198 @code{preview} as graphic images for some other application. One
199 possibility is to generate a flurry of @acronym{EPS} files with
202 dvips -E -i -Pwww -o @var{outputfile}.000 @var{inputfile}
206 However, in case those are to be processed further into graphic
207 image files by Ghostscript, this process is inefficient since all
208 of those files need to be processed one by one. In addition, it
209 is necessary to extract the bounding box comments from the @acronym{EPS}
210 files and convert them into page dimension parameters for
211 Ghostscript in order to avoid full-page graphics. This is not
212 even possible if you wanted to use Ghostscript in a@w{ }@emph{single}
213 run for generating the files from a single PostScript file, since
214 Dvips will in that case leave no bounding box information
217 The solution is to use the @code{tightpage} option. That way a single
221 @option{gs -sDEVICE=png16m -dTextAlphaBits=4 -r300
222 -dGraphicsAlphaBits=4 -dSAFER -q -dNOPAUSE
223 -sOutputFile=@var{outputfile}%d.png @var{inputfile}.ps}
227 will be able to produce tight graphics from a single PostScript
228 file generated with Dvips @emph{without} use of the options
229 @code{-E -i}, in a single run.
231 The @code{tightpage} option actually also works when using the @code{pdftex}
232 option and generating PDF files with PDF@TeX{}. The resulting PDF
233 file has separate page dimensions for every page and can directly
234 be converted with one run of Ghostscript into image files.
236 If neither @code{dvips} or @code{pdftex} have been specified, the
237 corresponding option will get autodetected and invoked.
239 If you need this in a batch environment where you don't want to
240 use @code{preview}'s automatic extraction facilities, no problem: just
241 don't use any of the extraction options, and wrap everything to be
242 previewed into @code{preview} environments. This is how LyX does its
245 If the pages under the @code{tightpage} option are just too tight, you
246 can adjust by setting the length @code{\PreviewBorder} to a different
247 value by using @code{\setlength}. The default value is
248 @file{0.50001bp}, which is half of a usual PostScript point, rounded
249 up. If you go below this value, the resulting page size may drop
250 below @code{1bp}, and Ghostscript does not seem to like that. If you
251 need finer control, you can adjust the bounding box dimensions
252 individually by changing the macro @code{\PreviewBbAdjust} with the
253 help of @code{\renewcommand}. Its default value is
256 \newcommand \PreviewBbAdjust
257 @{-\PreviewBorder -\PreviewBorder
258 \PreviewBorder \PreviewBorder@}
262 This adjusts the left, lower, right and upper borders by the given
263 amount. The macro must contain 4@w{ }@TeX{} dimensions after another,
264 and you may not omit the units if you specify them explicitly
265 instead of by register. PostScript points have the unit@w{ }@code{bp}.
267 This option is for the sake of LyX developers. It will
268 output a few diagnostics relevant for the sake of LyX' preview
269 functionality (at the time of writing, mostly implemented for math
270 insets, in versions of LyX starting with 1.3.0).
271 @item @code{counters}
272 This writes out diagnostics at the start and the
273 end of previews. Only the counters changed since the last output
274 get written, and if no counters changed, nothing gets written at
275 all. The list consists of counter name and value, both enclosed
276 in @code{@{@}} braces, followed by a space. The last such pair is
277 followed by a colon (@code{:}) if it is at the start of the preview
278 snippet, and by a period (@file{.}) if it is at the end. The order of
279 different diagnostics like this being issued depends on the order
280 of the specification of the options when calling the package.
282 Systems like @previewlatex{} use this for keeping counters accurate
283 when single previews are regenerated.
284 @item @code{footnotes}
285 This makes footnotes render as previews, and only
286 as their footnote symbol. A convenient editing feature inside of
290 The following options are just for debugging purposes of the package
291 and similar to the corresponding @TeX{} commands they allude to:
294 @item @code{tracingall}
295 causes lots of diagnostic output to appear in
296 the log file during the preview collecting phases of @TeX{}'s
297 operation. In contrast to the similarly named @TeX{} command, it
298 will not switch to @code{\errorstopmode}, nor will it change the
299 setting of @code{\tracingonline}.
301 This option will show the contents of the boxes
302 shipped out to the @acronym{DVI} files. It also sets @code{\showboxbreadth} and
303 @code{\showboxdepth} to their maximum values at the end of loading this
304 package, but you may reset them if you don't like that.
307 @node Provided commands, ,Package options, The LaTeX style file
308 @subsection Provided commands
311 @item \begin@{preview@}@dots{}\end@{preview@}
312 The @code{preview} environment causes its contents
313 to be set as a single preview image. Insertions like figures and
314 footnotes (except those included in minipages) will typically lead
315 to error messages or be lost. In case the @code{preview} package has not
316 been activated, the contents of this environment will be typeset
319 @item \begin@{nopreview@}@dots{}\end@{nopreview@}
320 The @code{nopreview} environment will cause its
321 contents not to undergo any special treatment by the @code{preview}
322 package. When @code{preview} is active, the contents will be discarded
323 like all main text that does not trigger the @code{preview} hooks. When
324 @code{preview} is not active, the contents will be typeset just like the
327 Note that both of these environments typeset things as usual when
328 preview is not active. If you need something typeset conditionally,
329 use the @code{\ifPreview} conditional for it.
332 If you want to make a macro like
333 @findex \PreviewMacro
334 @code{\includegraphics} (actually, this is what is done by the
335 @code{graphics} option to @code{preview}) produce a preview image, you put a
339 \PreviewMacro[*[[!]@{\includegraphics@}
346 \PreviewMacro[@{*[][]@{@}@}]@{\includegraphics@}
350 into your preamble. The optional argument to @code{\PreviewMacro}
351 specifies the arguments @code{\includegraphics} accepts, since this
352 is necessary information for properly ending the preview box. Note
353 that if you are using the more readable form, you have to enclose
354 the argument in a @code{[@{} and @code{@}]} pair. The inner braces are
355 necessary to stop any included @code{[]} pairs from prematurely ending
356 the optional argument, and to make a single @code{@{@}}
357 denoting an optional argument not get stripped away by @TeX{}'s
360 The letters simply mean
364 indicates an optional @code{*} modifier, as in
365 @code{\includegraphics*}.
368 indicates an optional argument in brackets. This syntax
369 is somewhat baroque, but brief.
371 also indicates an optional argument in brackets. Be
372 sure to have encluded the entire optional argument specification
373 in an additional pair of braces as described above.
375 indicates a mandatory argument.
377 indicates the same. Again, be sure to have
378 that additional level of braces around the whole argument
380 @item @code{?}@var{delimiter}@{@var{true case}@}@{@var{false case}@}
382 conditional. The next character is checked against being equal to
383 @var{delimiter}. If it is, the specification @var{true case} is
384 used for the further parsing, otherwise @var{false case} will be
385 employed. In neither case is something consumed from the input,
386 so @{@var{true case}@} will still have to deal with the upcoming
388 @item @code{@@}@{@var{literal sequence}@}
389 will insert the given sequence
390 literally into the executed call of the command.
392 will just drop the next token. It will probably be most
393 often used in the true branch of a @code{?} specification.
394 @item @code{#}@{@var{argument}@}@{@var{replacement}@}
396 rule that calls a macro with the given argument and replacement
397 text on the rest of the argument list. The replacement is used in
398 the executed call of the command. This can be used for parsing
399 arbitrary constructs. For example, the @code{[]} option could manually
400 be implemented with the option string @code{?[@{#@{[#1]@}@{[@{#1@}]@}@}@{@}}.
401 PStricks users might enjoy this sort of flexibility.
402 @item @code{:}@{@var{argument}@}@{@var{replacement}@}
404 transformation rule. As opposed to @code{#}, however, the result of
405 the transformation is parsed again. You'll rarely need this.
409 There is a second optional argument in brackets that can be used to
410 declare any default action to be taken instead. This is mostly for
411 the sake of macros that influence numbering: you would want to keep
412 their effects in that respect. The default action should use @code{#1}
413 for referring to the original (not the patched) command with the
414 parsed options appended. Not specifying a second optional argument
415 here is equivalent to specifying@w{ }@code{[#1]}.
419 @code{\PreviewMacro*} simply throws the macro and all of its
420 arguments declared in the manner above away. This is mostly useful
421 for having things like @code{\footnote} not do their magic on their
422 arguments. More often than not, you don't want to declare any
423 arguments to scan to @code{\PreviewMacro*} since you would want the
424 remaining arguments to be treated as usual text and typeset in that
425 manner instead of being thrown away. An exception might be, say,
426 sort keys for @code{\cite}.
428 A second optional argument in brackets can be used to declare any
429 default action to be taken instead. This is for the sake of macros
430 that influence numbering: you would want to keep their effects in
431 that respect. The default action might use @code{#1} for referring to
432 the original (not the patched) command with the parsed options
433 appended. Not specifying a second optional argument here is
434 equivalent to specifying@w{ }@code{[]} since the command usually gets thrown
437 As an example for using this argument, you might want to specify
440 \PreviewMacro*[@{[]@}][#1@{@}]@{\footnote@}
444 This will replace a footnote by an empty footnote, but taking any
445 optional parameter into account, since an optional paramter changes
446 the numbering scheme. That way the real argument for the footnote
447 remains for processing by @previewlatex{}.
449 @item \PreviewEnvironment
451 @findex \PreviewEnvironment
452 @code{\PreviewEnvironment} works just as @code{\PreviewMacro} does,
453 only for environments. @item \PreviewEnvironment*
455 same goes for @code{\PreviewEnvironment*} as compared to
456 @code{\PreviewMacro*}.
458 @item \PreviewSnarfEnvironment
459 This macro does not typeset
460 the original environment inside of a preview box, but instead
461 typesets just the contents of the original environment inside of the
462 preview box, leaving nothing for the original environment. This has
463 to be used for figures, for example, since they would
466 @item produce insertion material that cannot be extracted to the
468 @item complain with an error message about not being in outer par
475 Those Macros form a matched preview pair. This is for macros that
476 behave similar as @code{\begin} and @code{\end} of an environment. It
477 is essential for the operation of @code{\PreviewOpen} that the macro
478 treated with it will open an additional group even when the preview
479 falls inside of another preview or inside of a @code{nopreview}
480 environment. Similarly, the macro treated with @code{\PreviewClose}
481 will close an environment even when inactive.
484 In case you need to know whether
485 @code{preview} is active, you can use the conditional @code{\ifPreview}
486 together with @code{\else} and @code{\fi}.