Debian Codegraph @

texmf-dist/source/latex/xsavebox/xsavebox.tex

raw
1 % Copyright 2007--\today Alexander Grahn
2 %
3 % This material is subject to the LaTeX Project Public License. See
4 % http://mirrors.ctan.org/macros/latex/base/lppl.txt
5 % for the details of that license.
6 %
7 \listfiles
8 %%%%%%% pdfmanagement-testphase %%%%%%
9 \DocumentMetadata % activates the PDF management interface
10 {
11 %uncompress,
12 }
13 %%%%%% /pdfmanagement-testphase %%%%%%
14 \documentclass[a4paper]{article}
15 \frenchspacing
16 \usepackage[UKenglish]{babel}
17 \usepackage{xsavebox}
18 \usepackage{csquotes}
19 \usepackage{graphicx}
20 \graphicspath{{files/}}
21 \usepackage{color}
22 %\usepackage{lmodern}
23 \usepackage[tt=false]{libertine} %override beramono (doesn't look like tt font)
24 \usepackage[libertine]{newtxmath}
25 \usepackage[T1]{fontenc}
26 \usepackage[protrusion,expansion]{microtype}
27 \usepackage{parskip}
28 \usepackage[bookmarksnumbered,linktocpage]{hyperref}
29 \usepackage[ocgcolorlinks]{ocgx2}
30 \usepackage{fancyvrb}
31 \clubpenalty=10000
32 \widowpenalty=10000
33 \displaywidowpenalty=10000
34 \renewcommand{\textfraction}{0.0}
35 \renewcommand{\topfraction}{1.0}
36 \renewcommand{\bottomfraction}{1.0}
37
38 \hypersetup{
39 pdftitle={The xsavebox Package},
40 pdfsubject={Documentation},
41 pdfauthor={Alexander Grahn},
42 pdfkeywords={PDF features, XObject, savebox, LaTeX, dvips, repeated content, repeated graphics, eps, PostScript, ps2pdf, XeLaTeX, pdfLaTeX, LuaLaTeX, dvipdfmx, dvisvgm},
43 allcolors=blue,
44 % pdfpagelayout=SinglePage
45 }
46
47 %\usepackage[scaled=0.85]{luximono}
48
49 \def\XeLaTeX{X\kern-.1667em\lower.5ex\hbox{\reflectbox{E}}\kern-.125em\LaTeX}
50 \def\XeTeX{X\kern-.1667em\lower.5ex\hbox{\reflectbox{E}}\kern-.125em\TeX}
51 \def\pXepLaTeX{(X\kern-.1667em\lower.5ex\hbox{\reflectbox{E}})\kern-.125em\LaTeX}
52
53 \def\parsedate#1/#2/#3\relax{
54 \def\year{#1}
55 \def\month{#2}
56 \def\day{#3}
57 }
58
59 \begin{document}
60 \makeatletter
61 \title{The {\sffamily xsavebox} Package, v\g@xsb@version@tl}
62 \expandafter\parsedate\g@xsb@date@tl\relax %set current date to package date
63 \makeatother
64 \author{Alexander Grahn\\[1ex]\url{https://gitlab.com/agrahn/xsavebox}}
65 \maketitle
66 \begin{abstract}
67 \noindent This package defines commands for saving content that can be repeatedly placed into the document without replicating DVI/PDF code in the output file, allowing for smaller size of the final PDF file and improved content caching for faster display in certain PDF viewers. The user commands are modelled after the standard \LaTeX{} commands \verb+\savebox+, \verb+\sbox+, \verb+\usebox+ and the `\verb+lrbox+' environment. The package supports all common \TeX{} engines and back-ends, including `\verb+dvips+', `\verb+(x)dvipdfmx+' and `\verb+dvisvgm+'.
68 \end{abstract}
69
70 \section{Introduction}
71 Whenever the standard \LaTeX{} command \verb+\usebox{+\emph{save-box}\verb+}+ is issued to insert a previously defined \emph{save-box} more than once, the typeset content stored therein is written as DVI or PDF code into the output file again. The redundant code adds to the overall file size and may impair the page caching facilities built into some PDF viewers.
72
73 The PDF file format defines a powerful mechanism for packing readily typeset content once into self-contained entities, so-called \enquote{Form XObjects}, that can be referenced at other places within the PDF document.
74
75 The `\verb+xsavebox+' package makes this PDF feature accessible on the \LaTeX{} level as a set of user commands which look similar to and are used in a similar way as the well-known \emph{save-box} related \LaTeX{} commands.
76
77 All common \TeX{} engines and back-ends are supported, which are:
78 \begin{itemize}
79 %\item $\varepsilon$-\TeX
80 \item pdf\LaTeX, Lua\LaTeX,
81 \item \LaTeX{} $\rightarrow$ \verb+dvips+ $\rightarrow$ \verb+ps2pdf+/Distiller
82 \item \pXepLaTeX{} $\rightarrow$ \verb+(x)dvipdfmx+
83 \item \pXepLaTeX{} $\rightarrow$ \verb+dvisvgm+
84 \end{itemize}
85
86 To enable `\verb+dvipdfmx+' or `\verb+dvisvgm+', pass them as document class option.
87
88 It should be emphasized that \enquote{Form XObjects} is a PDF feature. Content saved and referenced using \enquote{Form XObjects} is only visible in the final PDF output, but not in intermediate formats of the work-flow if those are involved, namely DVI and PostScript. Of course, PostScript converted back from PDF displays the content correctly.
89
90 \section{Package Options}
91 \begin{Verbatim}
92 margin=<dimension>
93 \end{Verbatim}
94 When content is converted into a Form XObject, it is clipped to its bounding box. However, the font glyphs used for typesetting tend to be slightly bigger than their boxes. In order to avoid clipping, the `\verb+xsavebox+' package \emph{temporarily} adds an additional margin of \verb+3pt+ around the content. In rare cases, \verb+3pt+ may turn out to be insufficient, e.\,g. if text is up-scaled before being put into a save box. This option allows the setting of a larger margin to ensure that the content gets entirely into the save box. Note that whichever value is chosen for `\verb+margin+', the spacing of the boxes, when inserted into the document, remains unchanged. This is what every user definitely wants.
95
96 \section{User commands}
97 \subsection*{Content saving}
98 \vspace{-1\baselineskip}
99 \hrulefill\\[-1.6\baselineskip]
100 \begin{Verbatim}
101 \xsbox{<xsbox name>}{<content>}
102 \xsavebox{<xsbox name>}[<width>][<position>]{<content>}
103 \xsavebox*{<xsbox name>}[<width>][<position>]{<content>}
104
105 \begin{xlrbox}{<xsbox name>}
106 <content>
107 \end{xlrbox}
108
109 \begin{xlrbox*}{<xsbox name>}
110 <content>
111 \end{xlrbox*}
112 \end{Verbatim}
113 \vspace{-1\baselineskip}
114 \hrulefill\\[-1\baselineskip]
115
116 As for usage, the main difference of these commands as compared to their standard \LaTeX{} counterparts without the leading `\verb+x+' is the way of naming boxes. The label \verb+<xsbox name>+ is an identifier that may be composed of arbitrary non-active characters, such as letters, numbers, spaces, punctuation marks. A command for declaring a box register does not exist; \verb+<xsbox name>+ is created upon using above-listed commands and environments. Also, an existing \verb+<xsbox name>+ can be re-used, which simply overwrites its old with new content. The package keeps track of box usage; the content of a box is only written to the output file if it is referenced at least once later in the document.
117
118 The \verb+[<width>]+ and \verb+[<position>]+ options have the same meaning as with \verb+\savebox+ and \verb+\makebox+. As usual, the additional length commands
119 \begin{Verbatim}
120 \width
121 \height
122 \depth
123 \totalheight
124 \end{Verbatim}
125 are defined for use in the \verb+[<width>]+ option and refer to the original dimensions of \verb+<content>+. The value of \verb+<position>+ may assume one of `\verb+l+', `\verb+r+', `\verb+c+' or `\verb+s+'. The default is `\verb+c+' for text centred in the box.
126
127 \verb+<content>+ is typeset in LR-mode. Longer text to be typeset in paragraph mode must be put into a \verb+\parbox+ or `\verb+minipage+'.
128
129 The starred (`\verb+*+') versions of the commands allow for later colour injection into the boxes at the place of their referencing. The colour which is active at the time of building the box is not saved with the content. This feature only works with pdf\LaTeX{} and Lua\LaTeX.
130
131 Note that
132 \begin{Verbatim}
133 \xsbox{image for frequent use}{\includegraphics{example}}
134 \end{Verbatim}
135 is particularly useful in the \LaTeX{} $\rightarrow$ \verb+dvips+ $\rightarrow$ \verb+ps2pdf+ work-flow. Although the other engines and back-ends already take care of preventing multiple graphics file inclusion, a noticeable reduction of compilation time will be achieved in general.
136
137 Verbatim content can only be saved using the `\verb+xlrbox[*]+' environment.
138
139 With \LaTeX{} in DVI mode and \XeLaTeX, box \emph{saving} commands should not be placed on a line of their own with empty lines above and below. For technical reasons this will produce an empty paragraph. Always place them at the beginning or at the end of a paragraph in the input file. Also, box saving commands cannot be placed in the document preamble with \LaTeX{} (DVI) and \XeLaTeX{}.
140
141 In a right-to-left typesetting context (RTL) using the (pdf)\LaTeX{} or \XeLaTeX{} engines, the \verb+<content>+ argument should be enclosed in a pair of \verb+\beginR+ and \verb+\endR+ commands for correct typesetting results.
142
143 \subsection*{Referencing saved content}
144 Previously saved content can be inserted with\\[-1.6\baselineskip]
145
146 \hrulefill\\[-1.6\baselineskip]
147 \begin{Verbatim}
148 \xusebox{<xsbox name>}
149 \end{Verbatim}
150 \vspace{-1ex}
151 or
152 \vspace{-1ex}
153 \begin{Verbatim}
154 \the<xsbox name>
155 \end{Verbatim}
156 \vspace{-1\baselineskip}
157 \hrulefill\\[-1\baselineskip]
158
159 The second, shorthand form can be used if \verb+<xsbox name>+ is composed exclusively of letters (`\verb+a+`--`\verb+z+', `\verb+A+`--`\verb+Z+'). For example, a box named `\verb+MyFirstExample+' could be referenced as
160 \begin{Verbatim}
161 \theMyFirstExample
162 \end{Verbatim}
163 but a box named `\verb+My 1st Example ;-)+' would require
164 \begin{Verbatim}
165 \xusebox{My 1st Example ;-)}
166 \end{Verbatim}
167
168 The referencing commands \verb+\xusebox{<xsbox name>}+ and \verb+\the<xsbox name>+ can again be placed inside the \verb+<content>+ body of box saving commands. There is no upper limit of nesting levels.
169
170 \verb+\xusebox{<xsbox name>}+ and \verb+\the<xsbox name>+ behave exacly like common \TeX{} boxes. Therefore, they can be scaled, rotated and resized using the corresponding commands from the `\verb+graphicx+' package.
171
172 \section{Example}
173 An example with colour injection (pdf\LaTeX/Lua\LaTeX-only) follows:
174
175 \begin{xlrbox*}{SavedPar}
176 \begin{minipage}[b]{1in}
177 silly boxed paragraph that no one will ever use
178 \end{minipage}
179 \end{xlrbox*}%
180 Here is a \fbox{\color{blue}\theSavedPar} for anything.
181
182 The same \fbox{\color{green}\rotatebox{90}{\theSavedPar}} was inserted again but with a different colour and rotated by 90 degree.
183
184 \begin{Verbatim}
185 \usepackage{xsavebox}
186 \usepackage{color}
187 \usepackage{graphicx}
188 ...
189 \begin{xlrbox*}{SavedPar}% `*' --> no colour at the time of saving
190 \begin{minipage}[b]{1in}
191 silly boxed paragraph that no one will ever use
192 \end{minipage}
193 \end{xlrbox*}
194 %colours injected into \theSavedPar
195 Here is a \fbox{\color{blue}\theSavedPar} for anything.
196
197 The same \fbox{\color{green}\rotatebox{90}{\theSavedPar}} was
198 inserted again but with a different colour and rotated by 90 degree.
199 \end{Verbatim}
200
201 \end{document}