Debian Codegraph @

texmf-dist/source/latex/minidocument/minidocument.dtx

raw
1 % \iffalse meta-comment
2 %
3 % Copyright 2017 Maurice Leclaire <[email protected]>
4 %
5 % This work may be distributed and/or modified under the
6 % conditions of the LaTeX Project Public License, either
7 % version 1.3 of this license or (at your option) any later
8 % version. The latest version of this license is in:
9 %
10 % http://www.latex-project.org/lppl.txt
11 %
12 % and version 1.3 or later is part of all distributions of LaTeX
13 % version 2005/12/01 or later.
14 %
15 % This work has the LPPL maintenance status `author-maintained'.
16 %
17 % This work consists of the files minidocument.dtx and minidocument.ins
18 % and the derived file minidocument.sty.
19 %
20 % \fi
21 %
22 % \iffalse
23 %<package>\NeedsTeXFormat{LaTeX2e}
24 %<package>\ProvidesPackage{minidocument}[2017/04/11 v1.0 Mini Documents]
25 %
26 %<*driver>
27 \documentclass{ltxdoc}
28 \CheckSum{109}
29 \usepackage{minidocument}
30 \usepackage{blindtext}
31 \EnableCrossrefs
32 \CodelineIndex
33 \RecordChanges
34 \begin{document}
35 \DocInput{minidocument.dtx}
36 \end{document}
37 %</driver>
38 % \fi
39 %
40 % \changes{v1.0}{2017/01/26}{Initial version}
41 %
42 % \GetFileInfo{minidocument.sty}
43 %
44 % %\DoNotIndex{\def,\let,\global,\long,\expandafter}
45 % %\DoNotIndex{\csname,\endcsname,\advance,\string}
46 % %\DoNotIndex{\if,\else,\fi,\ifdim,\ifodd,\ifvoid,\ifcsname,\@ifnextchar}
47 % %\DoNotIndex{\chardef,\count,\dimen,\skip,\box,\setbox,\lastbox,\copy}
48 % %\DoNotIndex{\hbox,\vbox,\unhbox,\unvbox,\hskip,\vskip,\hss,\hrule,\vfill}
49 % %\DoNotIndex{\the,\ht,\dp,\@ne,\z@,\maxdimen}
50 %
51 % \title{The \textsf{minidocument} package}
52 % \author{Maurice Leclaire\\\texttt{[email protected]}}
53 % \date{\fileversion\ -- \filedate}
54 % \maketitle
55 %
56 % \begin{abstract}
57 % The \textsf{minidocument} package is used to create miniature documents inside
58 % other documents as can be seen in Figure~\ref{fig:example}.
59 % \end{abstract}
60 %
61 % \begin{minidocument}
62 % \def\minidocumentscale{0.25}
63 % \title{The \textsf{minidocument} package}
64 % \author{Maurice Leclaire\\\texttt{[email protected]}}
65 % \date{\fileversion\ -- \filedate}
66 % \maketitle
67 % \Blindtext
68 % \end{minidocument}
69 %
70 % \begin{figure}[!htb]
71 % \begin{center}
72 % \lastminidocument
73 % \end{center}
74 % \caption{A minidocument example}
75 % \label{fig:example}
76 % \end{figure}
77 %
78 % \tableofcontents
79 %
80 % \section{Usage}
81 %
82 % \DescribeEnv{minidocument}
83 % A minidocument is created with the \verb|minidocument| environment.
84 % The \verb|page| counter is set to one at the beginning of a minidocument and
85 % restored afterwards.
86 % It is important, that this environment is placed in outer vertical mode.
87 % Otherwise, it will not work properly.
88 % However, it is of course possible to place the resulting minidocument
89 % everywhere. Therefore, the environment itself does not output anything. The
90 % example minidocument in Figure~\ref{fig:example} is defined as:
91 % \begin{quote}
92 % \begin{verbatim}
93 %\begin{minidocument}
94 % \maketitle
95 % \Blindtext
96 %\end{minidocument}
97 % \end{verbatim}
98 % \end{quote}
99 %
100 % \noindent
101 % \DescribeMacro{\lastminidocument}
102 % To output the minidocument, the command \verb|\lastminidocument| is used,
103 % e.\,g.:
104 % \begin{quote}
105 % \begin{verbatim}
106 %\begin{figure}
107 % \lastminidocument
108 %\end{figure}
109 % \end{verbatim}
110 % \end{quote}
111 %
112 % \noindent
113 % \DescribeMacro{\minidocumentscale}
114 % By default, the minidocument is scaled down with \verb|\minidocumentscale|,
115 % which defaults to 0.333. This can be changed with e.\,g.
116 % \begin{quote}
117 % \verb|\def\minidocumentscale{0.25}|
118 % \end{quote}
119 % as it is done in this documentation.
120 %
121 % \noindent
122 % \DescribeMacro{\minidocumentshipout}
123 % The macro \verb|\minidocumentshipout| is called for every page in the
124 % minidocument. It takes a single argument containing the page and is
125 % responsible for postprocessing it. It can be redefined to obtain a different
126 % look. The default is defined as
127 % \begin{quote}
128 % \verb|\scalebox{\minidocumentscale}{\frame{#1}}|
129 % \end{quote}
130 %
131 % \StopEventually{
132 % \begin{thebibliography}{1}
133 % \raggedright
134 % \bibitem{atbegshi}
135 % Heiko Oberdiek.
136 % \newblock The \textsf{atbegshi} package.
137 % \newblock \textsc{ctan}: \url{http://ctan.org/pkg/atbegshi}
138 % \end{thebibliography}
139 % \PrintChanges
140 % \setcounter{IndexColumns}{2}
141 % \PrintIndex
142 % }
143 %
144 % \section{Implementation}
145 %
146 % The \verb|graphics| package is required for \verb|\scalebox|.
147 % \begin{macrocode}
148 \RequirePackage{graphics}
149 % \end{macrocode}
150 %
151 % \begin{macro}{\minidocument@box}
152 % We allocate a box register for temporary storage.
153 % \begin{macrocode}
154 \newbox\minidocument@box
155 % \end{macrocode}
156 % \end{macro}
157 % \begin{macro}{\minidocument@aggrbox}
158 % The following box will aggregate the minidocument.
159 % \begin{macrocode}
160 \newbox\minidocument@aggrbox
161 % \end{macrocode}
162 % \end{macro}
163 % \begin{macro}{\minidocument@hold}
164 % This box is used to store the current vertical list when entering the
165 % minidocument.
166 % \begin{macrocode}
167 \newbox\minidocument@hold
168 % \end{macrocode}
169 % \end{macro}
170 %
171 % \begin{macro}{\minidocument@orig@output}
172 % We need a token register to store the output routine.
173 % \begin{macrocode}
174 \newtoks\minidocument@orig@output
175 % \end{macrocode}
176 % \end{macro}
177 %
178 % \noindent
179 % The following method of overloading the shipout procedure is borrowed from
180 % the \textsf{atbegshi} package\cite{atbegshi} where it is explained in detail.
181 % The problem we face here is that \verb|\shipout| can be called with many
182 % different box specifications which can not be catched as macro arguments.
183 % Therefore, we use \verb|\setbox| to get the box specification and
184 % \verb|\afterassignment| to execute the code that handles the box. However,
185 % for direct box specifications the code specified via \verb|\afterassignment|
186 % is not executed after the box specification is finished but directly at the
187 % beginning of the box. Therefore, we need an additional \verb|\aftergroup| in
188 % the case of a direct box. We only have to determine if we are at the
189 % beginning of a direct box. We can do this by inspecting \verb|\lastkern| as
190 % it is zero at the beginning of a box.
191 %
192 % \begin{macro}{\minidocument@shipout}
193 % This macro is the entry point of our shipout procedure. Inside a new group we
194 % assign and start a new box with a specified kerning. This box is only
195 % temporary and gives us a reliable environment. We install the
196 % \verb|\afterassignment| hook and assign the passed box to a box register. This
197 % assignment is global as it must survive the group while the temporary box
198 % which is assigned to the same box register is lost.
199 % \begin{macrocode}
200 \def\minidocument@shipout{%
201 \begingroup\setbox\minidocument@box\hbox\bgroup\kern\p@%
202 \afterassignment\minidocument@testshipout%
203 \global\setbox\minidocument@box%
204 }
205 % \end{macrocode}
206 % \end{macro}
207 % \begin{macro}{\minidocument@testshipout}
208 % The following macro is called by \verb|\afterassignment|. It checks via
209 % \verb|\lastkern| if it is called at the beginning of a box. In this case an
210 % \verb|\aftergroup| is inserted. Either way, when the box is finished the next
211 % macro is called.
212 % \begin{macrocode}
213 \def\minidocument@testshipout{%
214 \ifdim\lastkern=\z@%
215 \expandafter\aftergroup%
216 \fi%
217 \minidocument@makeshipout%
218 }
219 % \end{macrocode}
220 % \end{macro}
221 % \begin{macro}{\minidocument@makeshipout}
222 % This macro ends the temporary box and the group. We now have the passed box
223 % in the box register. If the box register is not void, we do the virtual
224 % shipout. Therefore, we position the box at the right place of a page.
225 % Afterwards, we call \verb|\minidocumentshipout| to postprocess the page. We
226 % then add the page to the aggregation box.
227 % \begin{macrocode}
228 \def\minidocument@makeshipout{%
229 \egroup\endgroup%
230 \ifvoid\minidocument@box\else%
231 \global\setbox\minidocument@box\vbox to \paperheight {
232 \vskip1in%
233 \hbox to \paperwidth {
234 \hskip1in%
235 \box\minidocument@box%
236 \hfill
237 }%
238 \vfill
239 }%
240 \global\setbox\minidocument@aggrbox\hbox{\unhbox\minidocument@aggrbox%
241 \minidocumentshipout{\box\minidocument@box}%
242 \hskip0pt%
243 }%
244 \fi%
245 }
246 % \end{macrocode}
247 % \end{macro}
248 %
249 % \begin{macro}{minidocument}
250 % The \verb|minidocument| environment first saves the current vertical list.
251 % Therefore, the output routine is changed and a page break is enforced. Then,
252 % the shipout procedure is switched and the page counter is set to one. At the
253 % end of the environment, the shipout procedure and the page number are
254 % restored. Afterwards, the saved vertical list is reinserted.
255 % \begin{macrocode}
256 \newenvironment{minidocument}{%
257 \minidocument@orig@output\output%
258 \output{\global\setbox\minidocument@hold\box\@cclv}%
259 \penalty-\@Mi%
260 \output\minidocument@orig@output%
261 \let\minidocument@orig@shipout\shipout%
262 \let\shipout\minidocument@shipout%
263 \edef\minidocument@page{\the\c@page}%
264 \c@page\@ne%
265 }{%
266 \clearpage%
267 \let\shipout\minidocument@orig@shipout%
268 \global\c@page\minidocument@page%
269 \unvbox\minidocument@hold%
270 }
271 % \end{macrocode}
272 % \end{macro}
273 %
274 % \begin{macro}{\lastminidocument}
275 % The macro \verb|\lastminidocument| unboxes the aggregated minidocument so
276 % that it can flow into the main document.
277 % \begin{macrocode}
278 \def\lastminidocument{%
279 \unhbox\minidocument@aggrbox\unskip%
280 }
281 % \end{macrocode}
282 % \end{macro}
283
284 % \begin{macro}{\minidocumentscale}
285 % We set the default scale factor to $1/3$, so that two pages can fit next to
286 % each other on a page with appropriate margins.
287 % \begin{macrocode}
288 \def\minidocumentscale{0.333}
289 % \end{macrocode}
290 % \end{macro}
291 % \begin{macro}{\minidocumentshipout}
292 % The default \verb|\minidocumentshipout| draws a frame around the page and
293 % scales the page with \verb|\minidocumentscale|.
294 % \begin{macrocode}
295 \newcommand{\minidocumentshipout}[1]{%
296 \scalebox{\minidocumentscale}{\frame{#1}}%
297 }
298 % \end{macrocode}
299 % \end{macro}
300 %
301 % \iffalse
302 \endinput
303 % \fi
304 %
305 % \Finale