summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/storebox
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2011-09-22 23:00:27 +0000
committerKarl Berry <karl@freefriends.org>2011-09-22 23:00:27 +0000
commit82f4934ee35dff8809425db64e550528f85c44d3 (patch)
tree72ab420d2763a90fed990113e3bee1005741293c /Master/texmf-dist/source/latex/storebox
parentb2c969266253a567831b99c3f564264d9e12c1d3 (diff)
new latex package storebox (22sep11)
git-svn-id: svn://tug.org/texlive/trunk@24068 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/storebox')
-rw-r--r--Master/texmf-dist/source/latex/storebox/storebox.dtx365
-rw-r--r--Master/texmf-dist/source/latex/storebox/storebox.ins10
2 files changed, 375 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/latex/storebox/storebox.dtx b/Master/texmf-dist/source/latex/storebox/storebox.dtx
new file mode 100644
index 00000000000..e690526682c
--- /dev/null
+++ b/Master/texmf-dist/source/latex/storebox/storebox.dtx
@@ -0,0 +1,365 @@
+% \iffalse meta-comment
+%<=*COPYRIGHT>
+%% 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.
+%%
+%<=/COPYRIGHT>
+% \fi
+%
+% \iffalse
+%<*driver>
+\ProvidesFile{storebox.dtx}[%
+%<=*DATE>
+ 2011/09/22
+%<=/DATE>
+%<=*VERSION>
+ v1.0
+%<=/VERSION>
+ DTX file for storebox]
+\documentclass{ydoc}
+\GetFileInfo{storebox.dtx}
+\usepackage{storebox}[\filedate]
+\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.}
+% \changes{v1.0}{2011/09/22}{First release.}
+%
+% \DoNotIndex{\newcommand,\newenvironment}
+%
+% \GetFileInfo{storebox.dtx}
+% \author{Martin Scharrer}
+% \email{martin@scharrer.me}
+% \ifdefined\repository
+% \repository{https://bitbucket.org/martin_scharrer/storebox}
+% \fi
+%
+% \maketitle
+%
+% \begin{abstract}\noindent
+% This package allows the placement of identical content multiple times in a document while only storing it once in the output file.
+% At the moment only \LaTeX\ compilers with native PDF output are supported (|pdflatex| or |lualatex|).
+% For other \LaTeX\ compilers a fallback to |\savebox| is implemented.
+% \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.sty>
+% \fi
+% \begin{macrocode}
+%<!COPYRIGHT>
+\ProvidesPackage{storebox}[%
+%<!DATE>
+%<!VERSION>
+%<*DRIVER>
+ 2099/01/01 develop
+%</DRIVER>
+ Store and reuse boxes in a file size efficient way]
+% \end{macrocode}
+%
+% \begin{macrocode}
+\DeclareOption{disable}{\let\ifstorebox\iffalse}
+\DeclareOption{enable}{\let\ifstorebox\iftrue}
+\ProcessOptions*
+\edef\@tempa{\@ptionlist{\@currname.\@currext}}
+\ifx\@tempa\empty
+ \RequirePackage{ifpdf}
+ \expandafter\let\csname ifstorebox\expandafter\endcsname\csname ifpdf\endcsname
+\fi
+% \end{macrocode}
+%
+% \begin{macrocode}
+\RequirePackage{collectbox}[2011/08/04]
+% \end{macrocode}
+%
+% \begin{macro}{\storebox}
+% \begin{macrocode}
+\newcommand*\storebox{%
+ \collectboxcheckenv{storebox}%
+ \ifcollectboxenv
+ \endgroup
+ \expandafter\@storebox@env
+ \else
+ \expandafter\@storebox
+ \fi
+}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macrocode}
+\ifstorebox
+% \end{macrocode}
+%
+% \begin{macro}{\@storebox}
+% Macro version:
+% \begin{macrocode}
+\def\@storebox#1{%
+ \begingroup
+ \@collectboxto\collectedbox{\pdfxform\collectedbox\endgroup\mathchardef#1=\pdflastxform}%
+}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\@storebox@env}
+% Environment version. Code adapted from \env{lrbox} environment. The group added by \Macro\begin and \Macro\end must
+% be specially handled to allow for a local assignment.
+% \begin{macrocode}
+\def\@storebox@env#1{%
+ \edef\@tempa{%
+ \setbox\collectedbox\hbox\bgroup%
+ \def\noexpand\@tempa{\noexpand#1}%
+ }%
+ \@tempa
+ \begingroup
+ \aftergroup\@storebox@env@end
+ \@endpefalse
+ \color@setgroup
+ \begingroup
+ \def\@currenvir{storebox\empty}%
+ \ignorespaces
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\@storebox@env@end}
+% This ends the box assignment and stores the box as PDF xform.
+% Then the given control sequence is set to the xform number.
+% \begin{macrocode}
+\def\@storebox@env@end{%
+ \edef\@tempa{%
+ \egroup
+ \pdfxform\collectedbox
+ \endgroup
+ \mathchardef\expandafter\noexpand\@tempa=\pdflastxform
+ }%
+ \@tempa
+}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\endstorebox}
+% \begin{macrocode}
+\def\endstorebox{%
+ \unskip
+ \endgroup
+ \color@endgroup
+}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\newstorebox}
+% \begin{macrocode}
+\newcommand*\newstorebox[1]{%
+ \@ifdefinable{#1}{\let#1\relax}%
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\usestorebox}
+% \begin{macrocode}
+\newcommand*\usestorebox[1]{%
+ \mbox{\pdfrefxform#1}%
+}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macrocode}
+\else
+% \end{macrocode}
+%
+%
+% \begin{macro}{\@storebox}
+% Macro version:
+% \begin{macrocode}
+\def\@storebox#1{\@collectboxto{#1}{}}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\@storebox@env}
+% \begin{macrocode}
+\def\@storebox@env{%
+ \edef\@currenvir{\@currenvir\noexpand\noexpand\noexpand\empty}%
+ \lrbox
+}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\endstorebox}
+% \begin{macrocode}
+\def\endstorebox{%
+ \endlrbox
+ \edef\@currenvir{\@currenvir}%
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\newsavebox}
+% \begin{macrocode}
+\@ifdefinable\newstorebox{%
+\let\newstorebox\newsavebox
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\usestorebox}
+% \begin{macrocode}
+\@ifdefinable\usestorebox{%
+\let\usestorebox\usebox
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macrocode}
+\fi
+% \end{macrocode}
+%
+
+% \iffalse
+%</storebox.sty>
+% \fi
+%
+% \Finale
+\endinput
diff --git a/Master/texmf-dist/source/latex/storebox/storebox.ins b/Master/texmf-dist/source/latex/storebox/storebox.ins
new file mode 100644
index 00000000000..51a9cd38708
--- /dev/null
+++ b/Master/texmf-dist/source/latex/storebox/storebox.ins
@@ -0,0 +1,10 @@
+\input ydocstrip.tex
+\keepsilent
+\askforoverwritefalse
+
+\generate{%
+ \file{storebox.sty}{\nopreamble\from{storebox.dtx}{storebox.sty}}%
+}
+\endbatchfile
+
+%% vim: ft=tex