preview.dtx.svn-base

moses开源的机器翻译系统

% 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 |[{| and |}]| pair.  The inner braces are
% necessary to stop any included |[]| pairs from prematurely ending
% the optional argument, and to make a single |{}|
% denoting an optional argument not get stripped away by \TeX's
% argument parsing.
% 
% The letters simply mean
% \begin{description}
% \item[|*|] indicates an optional |*| modifier, as in
%   |\includegraphics*|.
% \item[|[|] indicates an optional argument in brackets.  This syntax
%   is somewhat baroque, but brief.
% \item[{|[]|}] 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[|!|] indicates a mandatory argument.
% \item[|\char`{\char`}|] indicates the same.  Again, be sure to have
%   that additional level of braces around the whole argument
%   specification.
% \item[|?|\meta{delimiter}\marg{true case}\marg{false case}] is a
%   conditional.  The next character is checked against being equal to
%   \meta{delimiter}.  If it is, the specification \meta{true case} is
%   used for the further parsing, otherwise \meta{false case} will be
%   employed.  In neither case is something consumed from the input,
%   so \marg{true case} will still have to deal with the upcoming
%   delimiter.
% \item[|@|\marg{literal sequence}] will insert the given sequence
%   literally into the executed call of the command.
% \item[|-|] will just drop the next token.  It will probably be most
%   often used in the true branch of a |?| specification.
% \item[|\#|\marg{argument}\marg{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 |[]| option could manually
%   be implemented with the option string |?[{#{[#1]}{[{#1}]}}{}|.
%   PStricks users might enjoy this sort of flexibility.
% \item[|:|\marg{argument}\marg{replacement}] is again a
%   transformation rule.  As opposed to |#|, however, the result of
%   the transformation is parsed again.  You'll rarely need this.
% \end{description}
% 
% 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 |#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~|[#1]|.
% 
% \DescribeMacro{\PreviewMacro*} A similar invocation
% \cmd{\PreviewMacro*} simply throws the macro and all of its
% arguments declared in the manner above away.  This is mostly useful
% for having things like \cmd{\footnote} not do their magic on their
% arguments.  More often than not, you don't want to declare any
% arguments to scan to \cmd{\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 \cmd{\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 |#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~|[]| since the command usually gets thrown
% away.
% 
% As an example for using this argument, you might want to specify
% \begin{quote}
%   |\PreviewMacro*\footnote[{[]}][#1{}]|
% \end{quote}
% 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.
% 
% \DescribeMacro{\PreviewEnvironment} The macro
% \cmd{\PreviewEnvironment} works just as \cmd{\PreviewMacro} does,
% only for environments.  \DescribeMacro{\PreviewEnvironment*} And the
% same goes for \cmd{\PreviewEnvironment*} as compared to
% \cmd{\PreviewMacro*}.
% 
% \DescribeMacro{\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
% \begin{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}
% 
% \DescribeMacro{\PreviewOpen}
% \DescribeMacro{\PreviewClose}
% Those Macros form a matched preview pair.  This is for macros that
% behave similar as \cmd{\begin} and \cmd{\end} of an environment.  It
% is essential for the operation of \cmd{\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 |nopreview|
% environment.  Similarly, the macro treated with \cmd{PreviewClose}
% will close an environment even when inactive.
% 
% \DescribeMacro{\ifPreview} In case you need to know whether
% |preview| is active, you can use the conditional \cmd{\ifPreview}
% together with |\else| and |\fi|.
%
% \StopEventually{}
% \section{The Implementation}
% Here we go: the start is somewhat obtuse since we figure out version
% number and date from RCS strings.  This should really be done at
% docstrip time instead.  Takers?
% \begin{macro}{\pr@version}
%    \begin{macrocode}
%<*style>
%<*!active>
\NeedsTeXFormat{LaTeX2e} \def\reserved@a #1#2$#3:
#4${\xdef#1{\reserved@c #2#4 $}} \def\reserved@c #1 #2${#1}
\begingroup \catcode`\_=12
\reserved@a\pr@version $Name:  $ \ifx\pr@version\@empty
\reserved@a\pr@version CVS-$Revision: 1.1 $ \endgroup \else
  \def\next release_{} \lccode`\_=`.
  \edef\next{\lowercase{\endgroup
    \def\noexpand\pr@version{\expandafter\next\pr@version}}} \next \fi
\reserved@a\next $Date: 2006/10/04 23:56:03 $
\edef\next{\noexpand\ProvidesPackage{preview}%
  [\next\space \pr@version\space (AUCTeX/preview-latex)]}
\next
%    \end{macrocode}
% \end{macro}
% Since many parts here will not be needed as long as the package is
% inactive, we will include them enclosed with |<*active>| and
% |</active>| guards.  That way, we can append all of this stuff at a
% place where it does not get loaded if not necessary.
%
%\begin{macro}{\ifPreview}
%  Setting the \cmd{\ifPreview} command should not be done by the
%  user, so we don't use \cmd{\newif} here.  As a consequence, there
%  are no \cmd{\Previewtrue} and \cmd{\Previewfalse} commands.
%    \begin{macrocode}
\let\ifPreview\iffalse
%</!active>
%    \end{macrocode}
%\end{macro}
%\begin{macro}{\ifpr@outer}
%  We don't allow previews inside of previews.  The macro
%  \cmd{\ifpr@outer} can be used for checking whether we are outside
%  of any preview code.
%    \begin{macrocode}
%<*active>
\newif\ifpr@outer
\pr@outertrue
%</active>
%    \end{macrocode}
%\end{macro}
%
%\begin{macro}{\preview@delay}
%  The usual meaning of \cmd{\preview@delay} is to just echo its
%  argument in normal |preview| operation.  If |preview| is inactive,
%  it swallows its argument.  If the |delayed| option is active, the
%  contents will be passed to the \cmd{\AtBeginDocument} hook.
%\begin{macro}{\pr@advise}
%  The core macro for modifying commands is \cmd{\pr@advise}.  You
%  pass it the original command name as first argument and what should
%  be executed before the saved original command as second argument.
%\begin{macro}{\pr@advise@ship}
%  The most often used macro for modifying commands is
%  \cmd{\pr@advise@ship}.  It receives three arguments.  The first is
%  the macro to modify, the second specifies some actions to be done
%  inside of a box to be created before the original macro gets
%  executed, the third one specifies actions after the original macro
%  got executed.
%\begin{macro}{\pr@loadcfg}
%  The macro \cmd{\pr@loadcfg} is used for loading in configuration
%  files, unless disabled by the |noconfig| option.
%    \begin{macrocode}
%<*!active>
\let\preview@delay=\@gobble
\let\pr@advise=\@gobbletwo
\long\def\pr@advise@ship#1#2#3{}
\def\pr@loadcfg#1{\InputIfFileExists{#1.cfg}{}{}}
\DeclareOption{noconfig}{\let\pr@loadcfg=\@gobble}
%    \end{macrocode}
%\begin{macro}{\pr@addto@front}
%  This adds code globally to the front of a macro.
%    \begin{macrocode}
\long\def\pr@addto@front#1#2{%
  \toks@{#2}\toks@\expandafter{\the\expandafter\toks@#1}%
  \xdef#1{\the\toks@}}
%    \end{macrocode}
% \end{macro}
% These commands get more interesting when |preview| is active:
%    \begin{macrocode}
\DeclareOption{active}{%
  \let\ifPreview\iftrue
  \def\pr@advise#1{%
    \expandafter\pr@adviseii\csname pr@\string#1\endcsname#1}%
  \long\def\pr@advise@ship#1#2#3{\pr@advise#1{\pr@protect@ship{#2}{#3}}}%
  \let\preview@delay\@firstofone}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% 
% \begin{macro}{\pr@adviseii}
%   Now \cmd{\pr@advise} needs its helper macro.  In order to avoid
%   recursive definitions, we advise only macros that are not yet
%   advised.  Or, more exactly, we throw away the old advice and only
%   take the new one.
%    \begin{macrocode}
\long\def\pr@adviseii#1#2#3{\preview@delay{%
  \ifx#1\relax \let#1#2\fi
  \toks@{#3#1}\long\edef#2{\the\toks@}}}
%    \end{macrocode}
%\end{macro}
%
% The |delayed| option is easy to implement: this is \emph{not} done
% with \cmd{\let} since at the course of document processing, \LaTeX\
% redefines \cmd{\AtBeginDocument} and we want to follow that
% redefinition.
%    \begin{macrocode}
\DeclareOption{delayed}{%
  \ifPreview \def\preview@delay{\AtBeginDocument}\fi
}
%    \end{macrocode}
%
%\begin{macro}{\ifpr@fixbb}
%  Another conditional.  \cmd{\ifpr@fixbb} tells us whether we want to
%  surround the typeset materials with invisible rules so that Dvips
%  gets the bounding boxes right for, say, pure PostScript inclusions.
%
%  If you are installing this on an operating system different from
%  the one |preview| has been developed on, you might want to redefine
%  |\pr@markerbox| in your |prdefault.cfg| file to use a file known to
%  be empty, like |/dev/null| is under Unix.  Make this redefinition
%  depend on \cmd{\ifpr@fixbb} since only then |\pr@markerbox| will be
%  defined.
%    \begin{macrocode}
\newif\ifpr@fixbb
\pr@fixbbfalse
\DeclareOption{psfixbb}{\ifPreview%
  \pr@fixbbtrue
  \newbox\pr@markerbox
  \setbox\pr@markerbox\hbox{\special{psfile=/dev/null}}\fi
}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\pr@graphicstype}
%   The |dvips| option redefines the |bop-hook| to reset the page
%   size.
%    \begin{macrocode}
\let\pr@graphicstype=\z@
\DeclareOption{dvips}{%
  \let\pr@graphicstype\@ne
  \preview@delay{\AtBeginDvi{%
      \special{!/preview@version(\pr@version)def}
      \special{!userdict begin/preview-bop-level 0 def%
      /bop-hook{/preview-bop-level dup load dup 0 le{/isls false def%
          /vsize 792 def/hsize 612 def}if 1 add store}bind def%
      /eop-hook{/preview-bop-level dup load dup 0 gt{1 sub}if
        store}bind def end}}}}
%    \end{macrocode}
% The |pdftex| option just sets \cmd{\pr@graphicstype}.
%    \begin{macrocode}
\DeclareOption{pdftex}{%
  \let\pr@graphicstype\tw@}
%</!active>
%    \end{macrocode}
% \end{macro}
% \subsection{The internals}
%
% Those are only needed if |preview| is active.
%    \begin{macrocode}
%<*active>
%    \end{macrocode}
% \begin{macro}{\pr@snippet}
%   \cmd{\pr@snippet} is the current snippet number.  We need a
%   separate counter to \cmd{\c@page} since several other commands
%   might fiddle with the page number.
%    \begin{macrocode}
\newcount\pr@snippet
\global\pr@snippet=1
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\pr@protect}
%   This macro gets one argument which is unpacked and executed in
%   typesetting situations where we are not yet inside of a preview.
%    \begin{macrocode}
\def\pr@protect{\ifx\protect\@typeset@protect
  \ifpr@outer \expandafter\expandafter\expandafter
     \@secondoftwo\fi\fi\@gobble}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\pr@protect@ship}
%   Now for the above mentioned \cmd{\pr@protect@ship}.  This gets
%   three arguments.  The first is what to do at the beginning of the
%   preview, the second what to do at the end, the third is the macro
%   where we stored the original definition.
%
%   In case we are not in a typesetting situation,
%   \cmd{\pr@protect@ship} leaves the stored macro to fend for its
%   own.  No better or worse protection than the original.  And we
%   only do anything different when \cmd{\ifpr@outer} turns out to be
%   true.
%    \begin{macrocode}
\def\pr@protect@ship{\pr@protect{\@firstoftwo\pr@startbox}%