Debian Codegraph @

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

raw
1 % \iffalse meta-comment
2 % pbox.dtx - DocStrip source code for the pbox package
3 % Copyright (C) 2003,2011 Simon Law
4 %
5 % This program is free software: you can redistribute it and/or modify
6 % it under the terms of the GNU General Public License as published by
7 % the Free Software Foundation, either version 3 of the License, or
8 % (at your option) any later version.
9 %
10 % This program is distributed in the hope that it will be useful,
11 % but WITHOUT ANY WARRANTY; without even the implied warranty of
12 % MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 % GNU General Public License for more details.
14 %
15 % You should have received a copy of the GNU General Public License
16 % along with this program. If not, see <http://www.gnu.org/licenses/>.
17 %
18 % \fi
19 % \iffalse
20 %<style>\NeedsTeXFormat{LaTeX2e}
21 %<style>\ProvidesPackage{pbox}[2011/12/07 v1.2 Dynamic parboxes]
22 %<*driver>
23 \NeedsTeXFormat{LaTeX2e}[1995/12/01]
24 \documentclass{ltxdoc}
25 \usepackage{pbox}
26 \usepackage{url}
27 \usepackage{textcomp}
28 \usepackage{fancyvrb}
29 \newlength{\ExampleWidth}
30 \setlength{\ExampleWidth}{3.5cm}
31 \fvset{gobble=6,numbersep=3pt,frame=single,
32 numbers=left,xleftmargin=5mm,xrightmargin=0pt}
33 \fvset{xrightmargin=\ExampleWidth}
34 \EnableCrossrefs
35 %\DisableCrossrefs % Say \DisableCrossrefs if index is ready
36 \CodelineIndex
37 \RecordChanges % Gather update information
38 %\OnlyDescription % comment out for implementation details
39 \OldMakeindex % use if your MakeIndex is pre-v2.9
40 %\setlength\hfuzz{15pt} % don't make so many
41 %\hbadness=7000 % over and under full box warnings
42 \begin{document}
43 \DocInput{pbox.dtx}
44 \end{document}
45 %</driver>
46 % \fi
47 %
48 % \StopEventually{\PrintIndex \PrintChanges}
49 % \CheckSum{77}
50 %
51 % \DoNotIndex{\begin}
52 % \DoNotIndex{\columnwidth}
53 % \DoNotIndex{\DeclareRobustCommand,\def}
54 % \DoNotIndex{\end,\equal}
55 % \DoNotIndex{\ifthenelse}
56 % \DoNotIndex{\lengthtest}
57 % \DoNotIndex{\makebox}
58 % \DoNotIndex{\newcommand,\newlength}
59 % \DoNotIndex{\parbox}
60 % \DoNotIndex{\relax,\RequirePackage}
61 % \DoNotIndex{\setlength,\settowidth}
62 % \setcounter{IndexColumns}{2}
63 %
64 % \CharacterTable
65 % {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
66 % 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
67 % Digits \0\1\2\3\4\5\6\7\8\9
68 % Exclamation \! Double quote \" Hash (number) \#
69 % Dollar \$ Percent \% Ampersand \&
70 % Acute accent \' Left paren \( Right paren \)
71 % Asterisk \* Plus \+ Comma \,
72 % Minus \- Point \. Solidus \/
73 % Colon \: Semicolon \; Less than \<
74 % Equals \= Greater than \> Question mark \?
75 % Commercial at \@ Left bracket \[ Backslash \\
76 % Right bracket \] Circumflex \^ Underscore \_
77 % Grave accent \` Left brace \{ Vertical bar \|
78 % Right brace \} Tilde \~}
79 %
80 % \changes{v1.1}{2011/11/24}{Switch to GPLv3.}
81 % \changes{v1.0}{2003/03/19}{Initial release.}
82 %
83 % \GetFileInfo{pbox.sty}
84 %
85 % \title{The \textsf{pbox} package\thanks{Version \fileversion,
86 % last revised \filedate}}
87 % \author{Simon Law \\ \url{[email protected]}}
88 % \maketitle
89 %^^A \tableofcontents
90 %
91 % \section{Introduction}
92 %
93 % Most skilled \LaTeX{} users are familiar with the various box
94 % commands. These commands include |\makebox|, |\framebox|, |\savebox|,
95 % and |\parbox|. These boxes takes a parameter that specifies the
96 % width of box to create. To simplify matters, there are the |\mbox|,
97 % |\fbox|, and |\sbox| commands that fit the box created to the size of
98 % its contents. Conspicuously absent, however, is a |\pbox| command.
99 %
100 % \section{A variable-width \texttt{\textbackslash parbox}}
101 %
102 % At first glance, it seems quite inappropriate to create a |\pbox|
103 % command. After all, the size of a multi-line box will most likely be
104 % limited by the |\textwidth| or |\columnwidth| of the text it encloses.
105 % When a line of text is too long, it will be wrapped by \TeX{}'s own
106 % line-breaking algorithms. However, there are certain circumstances
107 % where one would want a variable-width |\parbox|.
108 %
109 % For example, you may want to align the top and bottom lines of
110 % multi-line boxes. The simplest way to do this is with |parbox|
111 % commands with an arbitrary width.
112 % \makeatletter
113 % \begingroup\center
114 % \begin{minipage}[c]{\ExampleWidth-5mm}
115 % \parbox[b]{1.5cm}{Hello\\World!}^^A
116 % \parbox[t]{1.5cm}{Bonjour\\monde!}
117 % \end{minipage}
118 % \begin{minipage}{\textwidth-\ExampleWidth}
119 % \fvset{xrightmargin=0pt}
120 % \begin{Verbatim}
121 % \parbox[b]{1.5cm}{Hello\\World!}%
122 % \parbox[t]{1.5cm}{Bonjour\\monde!}
123 % \end{Verbatim}
124 % \end{minipage}
125 % \endcenter\endgroup
126 % \makeatother
127 %
128 % \begin{DescribeMacro}{\pbox}
129 % However, this is not convenient. It may take several attempts to
130 % guess the correct width; and if there was ever a need to change the
131 % contents of the boxes, then the hard-coded widths must be changed as
132 % well. It would ideal to have a box that would collapse to the
133 % minimal required width.
134 % \makeatletter
135 % \begingroup\center
136 % \begin{minipage}[c]{\ExampleWidth-5mm}
137 % \pbox[b]{0.5\textwidth}{Hello\\World!}^^A
138 % \pbox[t]{0.5\textwidth}{Bonjour\\monde!}
139 % \end{minipage}
140 % \begin{minipage}{\textwidth-\ExampleWidth}
141 % \fvset{xrightmargin=0pt}
142 % \begin{Verbatim}
143 % \pbox[b]{0.5\textwidth}{Hello\\World!}%
144 % \pbox[t]{0.5\textwidth}{Bonjour\\monde!}
145 % \end{Verbatim}
146 % \end{minipage}
147 % \endcenter\endgroup
148 % \makeatother
149 % Notice how the exclaimation mark and the capital B have no extra
150 % space between each other, implying that |\pbox| creates minimal-width
151 % boxes.
152 %
153 % If the provided width argument is smaller than the minimal-width,
154 % then |\pbox| acts just like a regular |\parbox|. By minimal-width,
155 % we mean the width of the unwrapped piece of text. You will have to
156 % put in line breaks, to make |\pbox| create the tightest bounding box.
157 %
158 % For instance, the following example tries to get |\pbox| to wrap its
159 % lines automatically.
160 % \makeatletter
161 % \begingroup\center
162 % \begin{minipage}[c]{\ExampleWidth-5mm}
163 % \pbox[b]{1.5cm}{Hello World!}^^A
164 % \pbox[t]{1.5cm}{Bonjour monde!}
165 % \end{minipage}
166 % \begin{minipage}{\textwidth-\ExampleWidth}
167 % \fvset{xrightmargin=0pt}
168 % \begin{Verbatim}
169 % \pbox[b]{1.5cm}{Hello World!}%
170 % \pbox[t]{1.5cm}{Bonjour monde!}
171 % \end{Verbatim}
172 % \end{minipage}
173 % \endcenter\endgroup
174 % \makeatother
175 % \end{DescribeMacro}
176 %
177 % \section{Determining minimum widths}
178 %
179 % This is all well and good, but how does one measure the width of one
180 % of these boxes? Well, a rather painful way would be to use
181 % |\settowidth| in conjunction with a |\parbox|. But it is far easier
182 % to do it with the new width commands.
183 %
184 % \begin{DescribeMacro}{\settominwidth}
185 % The |\settominwidth| command works very similarly to the standard
186 % |\settowidth| command.
187 % \begin{description}
188 % \item
189 % |\settowidth[|\textit{max\_width}|]{|\textit{cmd}|}{|\textit{text}|}|
190 % sets the value of the a length command \textit{cmd} equal to the width
191 % of the multi-line \textit{text}. The optional argument
192 % \textit{max\_width} allows you to specify the maximum width that will
193 % be returned; it defaults to |\columnwidth|.
194 % \end{description}
195 % \end{DescribeMacro}
196 %
197 % \begin{DescribeMacro}{\widthofpbox}
198 % To provide completeness for the \textsf{calc} package, the
199 % |\widthofpbox| command was implemented to complement the |\widthof|
200 % command.
201 % \begin{description}
202 % \item
203 % |\widthofpbox{|\textit{text}|}| returns the width of the multi-line
204 % \textit{text}.
205 % \end{description}
206 % Here is an example:
207 % \makeatletter
208 % \begingroup\center
209 % \begin{minipage}[c]{\ExampleWidth-5mm}
210 % I\\
211 % need\\
212 % support\\
213 % \rule{\widthofpbox{I\\need\\support}}{0.4pt}
214 % \end{minipage}
215 % \begin{minipage}{\textwidth-\ExampleWidth}
216 % \fvset{xrightmargin=0pt}
217 % \begin{Verbatim}
218 % I\\
219 % need\\
220 % support\\
221 % \rule{\widthofpbox{I\\need\\support}}{0.4pt}
222 % \end{Verbatim}
223 % \end{minipage}
224 % \endcenter\endgroup
225 % \makeatother
226 % \end{DescribeMacro}
227 %
228 % \section{Limitations}
229 %
230 % Unfortunately, there are some limitations in this package. One of the
231 % intrinsic limitations is that you cannot do anything in a |\pbox| that
232 % you could not do in a |\parbox|. This seems quite reasonable, so
233 % it should not be a hardship.
234 %
235 % Since |\pbox| is implemented using the \textbf{tabular} environment,
236 % there are some things that cannot, and should not be used. You should
237 % note that errant |&| characters within a |\pbox| do not generate
238 % meaningful error messages. As well, it is unfortunate that
239 % |\linebreak| and |\newline| do not work as expected.
240 %
241 % Since it is a box, you cannot use the \textbf{verbatim} environment
242 % within. I recommend that you use the \textsf{fancyvrb} package which
243 % contains the \textbf{BVerbatim} and \textbf{LVerbatim} environments
244 % for typesetting boxed verbatim text.
245 %
246 % Alas, I have also discovered that certain uses of |\widthof| and
247 % |\widthofpbox| do not work within the \textsf{docstrip} environment.
248 %
249 % \newpage
250 % \section{Implementation}
251 % \iffalse
252 %<*style>
253 % \fi
254 %
255 % I use the standard \textsf{calc} package for general math. As well,
256 % I wish % to support a |\widthofpbox| command, so I will demand that the
257 % |\widthof| command exists as well.
258 % \begin{macrocode}
259 \RequirePackage{calc}
260 % \end{macrocode}
261 %
262 % In order to perform |\lengthtest|s and |\equal|ity tests, I need to
263 % include the standard \textsf{ifthen} package. This also provides me
264 % with simple conditionals.
265 % \begin{macrocode}
266 \RequirePackage{ifthen}
267 % \end{macrocode}
268 %
269 % \begin{macro}{\settominwidth}
270 % \changes{v1.1}{2011/11/24}{Always return a robust value.}
271 % \changes{v1.2}{2011/12/07}{Really fix the result.}
272 % The minimum length is determined by the clever use of the
273 % \textbf{tabular} environment. It knows how to calculate the minimum
274 % requisite width for a column, and the way determines the end of a
275 % column is with its end of row command |\\| .
276 % This command is conveniently similar to the command typically used to
277 % break lines.
278 %
279 % As you can see, |#1| defaults to the width of a column. This will
280 % either be |\textwidth| or the width defined by the \textbf{twocolumn}
281 % option, or even the \textsf{multicol} package.
282 % \begin{macrocode}
283 \newcommand{\settominwidth}[3][\columnwidth]{%
284 % \end{macrocode}
285 % Here, I set the length command |#2|. Notice the argument to the
286 % \textbf{tabular} environment. I use |@{}| to eliminate any horizontal
287 % padding, and use the |l| alignment to grab the width of the text in
288 % |#3|.
289 % \begin{macrocode}
290 \settowidth{#2}{\begin{tabular}{@{}l@{}}#3\end{tabular}}%
291 % \end{macrocode}
292 % Finally, I wish to make sure that the length I have set in |#2| is
293 % not larger than the maximum stored in |#1|.
294 % \begin{macrocode}
295 \ifthenelse{\lengthtest{#1<#2}}{\setlength{#2}{#1}}{}}
296 % \end{macrocode}
297 % \end{macro}
298 %
299 % \begin{macro}{\widthofpbox}
300 % In order to find the width of a |\pbox|, I use the same
301 % \textbf{tabular} trick from |\settominwidth|. I use the |\widthof|
302 % command in order to preserve its semantics instead of trying to
303 % emulate them using my |\settominwidth| command.
304 %
305 % I do \emph{not} check against a maximum length here. Restricting this
306 % command to a maximum length would mean that I throw away length
307 % information if the text is too long.
308 % \begin{macrocode}
309 \newcommand{\widthofpbox}[1]{%
310 \widthof{\begin{tabular}{@{}l@{}}#1\end{tabular}}}
311 % \end{macrocode}
312 % \end{macro}
313 %
314 % \begin{macro}{\pbox}
315 % \begin{macro}{\pb@xi}
316 % \begin{macro}{\pb@xii}
317 % It is not possible to implement |\pbox| in a simple way. The command
318 % definition commands in \LaTeX{} don't afford you more than one
319 % optional parameter; however, |\parbox| has three.
320 %
321 % In order to faithfully simulate the three optional arguments, I must
322 % trick \LaTeX{} in to catching three optional
323 % arguments~\cite{fto:optargs}. Therefore |\pbox|,
324 % |\pb@xi|, and |\pb@xii| are used to capture the optional arguments in
325 % the |\pb@xargi|, |\pb@xargii|, and |\pb@xargiii| commands. These are
326 % then passsed to |\pb@xiii| for actual processing.
327 % \begin{macrocode}
328 \DeclareRobustCommand*{\pbox}[1][]{%
329 \def\pb@xargi{#1}%
330 \pb@xi}
331 \DeclareRobustCommand*{\pb@xi}[1][]{%
332 \def\pb@xargii{#1}%
333 \pb@xii}
334 \DeclareRobustCommand*{\pb@xii}[1][]{%
335 \def\pb@xargiii{#1}%
336 \pb@xiii}
337 % \end{macrocode}
338 % \end{macro}
339 % \end{macro}
340 % \end{macro}
341 %
342 % \begin{macro}{\pb@xiii}
343 % In order to create the final paragraph box, I parse out the two
344 % manditory arguments. I then use the provided maximal length |#1| to
345 % determine the actual width of the |\parbox|.
346 % \begin{macrocode}
347 \newlength{\pb@xlen}
348 \DeclareRobustCommand{\pb@xiii}[2]{%
349 \settominwidth[#1]{\pb@xlen}{#2}%
350 % \end{macrocode}
351 %
352 % Since the default optional arguments are all empty, I should be able
353 % to just pass them to |\parbox|. However, |\parbox| interprets empty
354 % optional values differently than just non-existant optional values.
355 % So, I must make complicated decisions; if an optional argument is
356 % empty, then I will just skip it..
357 % \begin{macrocode}
358 \ifthenelse{\equal{\pb@xargi}{}}
359 {\parbox{\pb@xlen}{#2}}
360 {\ifthenelse{\equal{\pb@xargii}{}}
361 {\ifthenelse{\equal{\pb@xargiii}{}}
362 {\parbox[\pb@xargi]{\pb@xlen}{#2}}
363 {\parbox[\pb@xargi][][\pb@xargiii]{\pb@xlen}{#2}}}
364 {\ifthenelse{\equal{\pb@xargiii}{}}
365 {\parbox[\pb@xargi][\pb@xargii]{\pb@xlen}{#2}}
366 {\parbox[\pb@xargi][\pb@xargii][\pb@xargiii]{\pb@xlen}{#2}}}}%
367 % \end{macrocode}
368 %
369 % Finally, I must clean up the optional arguments and remove their
370 % special meaning. As well, I will terminate the |\parbox| I have
371 % created with an empty |\makebox| in order to prevent the
372 % |\def\pb@x...\relax| commands from interfering with other commands
373 % that expect |\pbox| to solely consist of a box.
374 % \begin{macrocode}
375 \def\pb@xargi\relax
376 \def\pb@xargii\relax
377 \def\pb@xargiii\relax
378 \makebox[0pt]{}}
379 % \end{macrocode}
380 % \end{macro}
381 % \iffalse
382 %</style>
383 % \fi
384 % \begin{thebibliography}{99}
385 % \bibitem{fto:optargs} Robin Fairbanks.
386 % ``A command with two optional arguments.''
387 % \emph{\TeX{} Frequently Asked Questions.}
388 % \url{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=twooptarg}
389 % (current 6 April 2003.)
390 % \end{thebibliography}
391 % \Finale
392 \endinput