1. Martin Scharrer
  2. adjustbox

Source

adjustbox / storebox.dtx

% \iffalse meta-comment
%
% Copyright (C) 2011 by Martin Scharrer <martin@scharrer-online.de>
% ---------------------------------------------------------------------------
% This work may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3
% of this license or (at your option) any later version.
% The latest version of this license is in
%   http://www.latex-project.org/lppl.txt
% and version 1.3 or later is part of all distributions of LaTeX
% version 2005/12/01 or later.
%
% This work has the LPPL maintenance status `maintained'.
%
% The Current Maintainer of this work is Martin Scharrer.
%
% This work consists of the files storebox.dtx and storebox.ins
% and the derived filebase storebox.sty.
%
% \fi
%
% \iffalse
%<*driver>
\ProvidesFile{storebox.dtx}
    [2011/08/05 v0.99 DTX File]
\documentclass{ydoc}
\usepackage{storebox}[2011/08/05]
\EnableCrossrefs
\CodelineIndex
\RecordChanges
\begin{document}
  \DocInput{\jobname.dtx}
  \PrintChanges
  \PrintIndex
\end{document}
%</driver>
% \fi
%
% \CheckSum{132}
%
% \CharacterTable
%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
%   Digits        \0\1\2\3\4\5\6\7\8\9
%   Exclamation   \!     Double quote  \"     Hash (number) \#
%   Dollar        \$     Percent       \%     Ampersand     \&
%   Acute accent  \'     Left paren    \(     Right paren   \)
%   Asterisk      \*     Plus          \+     Comma         \,
%   Minus         \-     Point         \.     Solidus       \/
%   Colon         \:     Semicolon     \;     Less than     \<
%   Equals        \=     Greater than  \>     Question mark \?
%   Commercial at \@     Left bracket  \[     Backslash     \\
%   Right bracket \]     Circumflex    \^     Underscore    \_
%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%   Right brace   \}     Tilde         \~}
%
%
% \changes{v0.99}{2011/08/05}{Converted to DTX file}
%
% \DoNotIndex{\newcommand,\newenvironment}
%
% \providecommand*{\url}{\texttt}
% \GetFileInfo{storebox.dtx}
% \title{The \textsf{storebox} package}
% \author{Martin Scharrer \\ \url{martin@scharrer-online.de}}
% \date{\fileversion~from \filedate}
% \makeatletter
% \def\@homepage{%
% Part of the \textsf{adjustbox} bundle\\
% \url{http://www.ctan.org/pkg/adjustbox}}
% \makeatother
%
% \maketitle
%
% \begin{abstract}\noindent
% Allows reuse of content multiple times in a document without while only storing it once in the output file.
% At the moment only PDF output is supported.
% \end{abstract}
%
% \section{Introduction}
% \LaTeX{} provides box registers to save content and use it later in the document once or multiple times (or none at all).
% However, the box content is then written every time to the output file.
% The PDF file format provides a way to store material as object and reference it later. A similar technique is theoretically
% possible for PostScript output (but not yet implemented). This has the benefit that the content is really only stored once
% in the output file. However, if file compression is used for the final output file the size benefit might be very small
% if the content is only reused a low number of times.
%
% This package provides ``store boxes'' which have the same user interface like normal \LaTeX{} ``save boxes'', but only 
% store the content once in the output file even if it is used several times.
% At the moment only PDF output is supported (i.e.\ \texttt{pdflatex} and \texttt{lualatex}).
% If the stored content is not used in the document after all it is not written to the PDF (at least the \texttt{pdftex} manual says so).
% For any other \TeX{} and output format the package simply falls back to use the normal savebox equivalents.
%
% \section{Options}
% The package should be loaded without any options and then automatically checks for PDF output (using the \pkg{ifpdf} package).
% It also provides two options \opt{enable} and \opt{disable} to explicitly switch the storebox feature on or off.
% The \opt{disable} option is useful to see the resulting file size difference.
% The usage of the \opt{enable} option should not be required and will lead to errors if used with unsupported \TeX{} formats.
%
% \Needspace*{3cm}
% \section{Macros}
%
% \DescribeMacro{\newstorebox}{<\textbackslash boxname>}
% Because storeboxes are stored as PDF objects and not as \TeX\ box registers
% it is not required to allocate a register for them. However, in fall-back mode
% the used control sequence \meta{\textbackslash boxname} must be defined as savebox.
% This macro defines \meta{\textbackslash boxname} simply as \Macro\relax\relax (just as precaution) and is equal to
% \Macro\newsavebox in fall-back mode.
%
%
% \DescribeMacro{\storebox}{<\textbackslash boxname>}{<content>}
% This stores the \meta{content} as \meta{\textbackslash boxname} (which is actually just a numeric reference) for later use.
% The \pkg{collectbox} package is used to collect the \meta{content} as box and not as macro argument and therefore it can
% contain verbatim and other special material. The braces can also be written in their explicit form \Macro\bgroup and \Macro\egroup
% and then split in two different macros or across the begin and end of an environment.
% It is possible to use \Macro\storebox multiple times with the same \meta{\textbackslash boxname}. This will create
% a new PDF object without affected the old one.
% In fall-back mode this macro is functional equal to \Macro\savebox\relax (but then still uses \pkg{collectbox}).
%
%
% \DescribeEnv[<content>]{storebox}{<\textbackslash boxname>}
% This is the environment version of \Macro\storebox. Special care is taken to allow for an identical name.
% In fall-back mode this macro is equal to the \env{lrbox} environment.
%
%
% \DescribeMacro{\usestorebox}{<\textbackslash boxname>}
% This macro typesets the stored content at the current position (as horizontal box in horizontal mode).
% This is realized by adding a PDF reference to the stored content.
% In fall-back mode this macro is equal to \Macro\usebox.
%
%
% \DescribeMacro{\ifstorebox}
% This if-switch is set to \emph{true} if \Macro\storebox was successfully defined as intended
% but to \emph{false} if the \Macro\savebox fall-back was used.
%
% \clearpage
% \section{Example}
% \begin{lstlisting}[gobble=2,language={[latex]tex},numbers=none]
% \documentclass{article}
%
% \usepackage{storebox}
%
% \newstorebox{\mybox} % Not really required for PDF output
% \begin{document}
%
% \storebox{\mybox}{\verb+Supports verbatim #$\empty+}
%
% \usestorebox{\mybox}
% \usestorebox{\mybox}
%
% \storebox\mybox\bgroup
% Can also be split
% \verb+\empty+
% \egroup
%
% \usestorebox{\mybox}
% \usestorebox{\mybox}
%
% \begin{storebox}{\mybox}
%     Or used as environment
%     (then will ignore leading and trailing spaces)
% \end{storebox}
%
% \usestorebox{\mybox}
% \usestorebox{\mybox}
%
% \end{document}
% \end{lstlisting}
%
% \setcounter{lstnumber}{1}
% \StopEventually{}
%
% \clearpage
% \section{Implementation}
%
% \iffalse
%<*storebox>
% \fi
% \iffalse
%</storebox>
% \fi
%
% \Finale
\endinput