preview.dtx.svn-base

moses开源的机器翻译系统

%%\iffalse
%%     preview.dtx for extracting previews from LaTeX documents.  Part of
%%     the preview-latex package.
%%     Copyright (C) 2001, 2002, 2003, 2004, 2005 Free Software Foundation
%%
%%     This program is free software; you can redistribute it and/or modify
%%     it under the terms of the GNU General Public License as published by
%%     the Free Software Foundation; either version 2 of the License, or
%%     (at your option) any later version.
%%
%%     This program is distributed in the hope that it will be useful,
%%     but WITHOUT ANY WARRANTY; without even the implied warranty of
%%     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
%%     GNU General Public License for more details.
%%
%%     You should have received a copy of the GNU General Public License
%%     along with this program; if not, write to the
%%     Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
%%     Boston, MA 02110-1301  USA
%%\fi
% \CheckSum{1640}
% \GetFileInfo{preview.sty}
% \date{\filedate}
% \author{David Kastrup\thanks{\texttt{[e-mail]}}}
% \title{The \texttt{preview} Package for \LaTeX\\Version \fileversion}
% \maketitle
% \section{Introduction}
% The main purpose of this package is the extraction of certain
% environments (most notably displayed formulas) from \LaTeX\ sources
% as graphics.  This works with 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 AUC\TeX\ 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 EPS files with Dvips and its derivatives using the
% \texttt{-E} option is not a good alternative: People make do by
% fiddling around with |\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'
% \begin{quote}
% |dvips -E -i|
% \end{quote}
% 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 |tightpage|
% option.  This will embed the page dimensions into the PostScript or
% PDF code, obliterating the need to use the |-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 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 DVI file with the options
% \begin{quote}
%   |-picky -noghostscript|
% \end{quote}
% 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.
% 
% \section{Package options}
% The package is included with the customary
% \begin{quote}
% |\usepackage|\oarg{options}|{preview}|
% \end{quote}
% 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:
% \begin{description}
% \item[|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
% \begin{quote}
% \raggedright
% |latex '\PassOptionsToPackage{active}{preview}| |\input|\marg{filename}|'|
% \end{quote}
% \item[|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.
% \item[|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.
% \item[|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[|pdftex|] If this option is set, PDF\TeX\ is assumed as the
%   output driver.  This mainly affects the |tightpage| option.
% \item[|displaymath|] will make all displayed math environments
%   subject to preview processing.  This will typically be the most
%   desired option.
% \item[|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
%   \cmd{\PreviewSnarfEnvironment} command on the floats you want to
%   have previewed.
% \item[|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 \cmd\(, \cmd\)
%   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.
% \item[|graphics|] will subject all \cmd{\includegraphics} commands
%   to a preview.
% \item[|sections|] will subject all section headers to a preview.
% \item[|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
%   \begin{quote}
%     |latex '\RequirePackage[active,delayed,|\meta{options}|]{preview}|
%     |\input|\marg{filename}|'|
%   \end{quote}
%   This relaxes the requirement to be loading the |preview| package
%   as last package.
% \item[\meta{driver}] loads a special driver file
%   |pr|\meta{driver}|.def|.  The remaining options are implemented
%   through the use of driver files.
% \item[|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 AUC\TeX\ 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 \cmd{\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.
% \item[|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 |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.
% \item[|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
%   \begin{quote}
%     |dvips -E -i -Pwww -o| \meta{outputfile}|.000| \meta{inputfile}
%   \end{quote}
%   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~\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 |tightpage| option.  That way a single
%   command line like
%   \begin{quote}
%     \raggedright
%     \texttt{gs -sDEVICE=png16m -dTextAlphaBits=4 -r300
%       -dGraphicsAlphaBits=4 -dSAFER -q -dNOPAUSE
%       -sOutputFile=\meta{outputfile}\%d.png \meta{inputfile}.ps}
%   \end{quote}
%   will be able to produce tight graphics from a single PostScript
%   file generated with Dvips \emph{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 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 |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 \cmd{\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
%   \begin{quote}
%     \raggedright
%     |\newcommand| |\PreviewBbAdjust|
%       |{-\PreviewBorder| |-\PreviewBorder|
%       |\PreviewBorder|  |\PreviewBorder}|
%   \end{quote}
%   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|.
% \item[|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[|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 \previewlatex\ use this for keeping counters accurate
%   when single previews are regenerated.
% \item[|footnotes|] This makes footnotes render as previews, and only
%   as their footnote symbol.  A convenient editing feature inside of
%   Emacs.
% \end{description}
% The following options are just for debugging purposes of the package
% and similar to the corresponding \TeX\ commands they allude to:
% \begin{description}
% \item[|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|.
% \item[|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.
% \end{description}
% \section{Provided Commands}
% \DescribeEnv{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.
% 
% \DescribeEnv{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 \cmd{\ifPreview} conditional for it.
% 
% \DescribeMacro{\PreviewMacro} If you want to make a macro like
% \cmd{\includegraphics} (actually, this is what is done by the
% |graphics| option to |preview|) produce a preview image, you put a
% declaration like
% \begin{quote}
% |\PreviewMacro[*[[!]{\includegraphics}|
% \end{quote}
% or, more readable,
% \begin{quote}
% |\PreviewMacro[{*[][]{}}]{\includegraphics}|
% \end{quote}
% into your preamble.  The optional argument to \cmd{\PreviewMacro}
% specifies the arguments \cmd{\includegraphics} accepts, since this