X-Git-Url: https://code.delx.au/gnu-emacs-elpa/blobdiff_plain/675826ae239d2fd710ffcc57e1b4cbb2fc300542..ebecf964123ab7b4e6deec85aa2f2fd58eddea29:/packages/auctex/doc/preview-dtxdoc.texi diff --git a/packages/auctex/doc/preview-dtxdoc.texi b/packages/auctex/doc/preview-dtxdoc.texi deleted file mode 100644 index a6cd64950..000000000 --- a/packages/auctex/doc/preview-dtxdoc.texi +++ /dev/null @@ -1,488 +0,0 @@ -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