Debian Codegraph @

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

raw
1 % \iffalse
2 %%
3 %% File `dashbox.dtx'.
4 %% Copyright (C) 1997-2001 Reuben Thomas ([email protected])
5 %% This file is distributed under the LaTeX Project Public License,
6 %% and comes with no warranty.
7 %%
8 %
9 %<*dtx>
10 \ProvidesFile{dashbox.dtx}
11 %</dtx>
12 %<driver> \ProvidesFile{dashbox.drv}
13 % \fi
14 %
15 % \iffalse
16 %<*driver>
17 \documentclass{ltxdoc}
18 \usepackage{url,dashbox}
19 \begin{document}
20 \DocInput{dashbox.dtx}
21 \end{document}
22 %</driver>
23 % \fi
24 %
25 % \GetFileInfo{dashbox.dtx}
26 % \CheckSum{336}
27 %
28 % \MakeShortVerb{\|}
29 %
30 % \changes{v1.00}{7 Mar 97}{First version (unreleased)}
31 % \changes{v1.10}{97}{Layered boxes added}
32 % \changes{v1.11}{2 Jun 97}{Minor formatting improvements; first release}
33 % \changes{v1.12}{28 Jul 01}{Made into a doc package; documentation
34 % added. Default number of layers changed to 3, and at signs inserted
35 % into private macro names. Tidied up some infelicities.}
36 % \changes{v1.13}{8 Aug 01}{Uncommented the TeX lines from
37 % |\NeedsTeXFormat| onwards; oops! Renamed to dashbox to avoid
38 % confusion.}
39 % \changes{v1.14}{11 Dec 01}{Changed ``dashed'' to ``dash'' in command
40 % names, to avoid confusion. Changed default number of layers back to 2.}
41 %
42 % \title{Dashed and layered boxes}
43 % \author{Reuben Thomas\\\url{[email protected]}}
44 % \date{11th December 2001}
45 % \maketitle
46 %
47 % \begin{abstract}
48 % |dashbox| provides new commands similar to |\framebox| and |\fbox|
49 % to typeset dashed and layered boxes.
50 % \end{abstract}
51 %
52 %
53 % \section{User interface}
54 %
55 % The following commands are provided:
56 %
57 % \begin{itemize}
58 % \item[]\hskip-\leftmargin
59 % \DescribeMacro{\dbox}
60 % |\dbox{|\textit{text}|}| works like |\fbox|, but the box is drawn
61 % with \dbox{dashed lines}.
62 % \item[]\hskip-\leftmargin
63 % \DescribeMacro{\dashbox}
64 % |\dashbox[|\textit{width}|][|\textit{pos}|]{|\textit{text}|}|
65 % works like |\framebox|, but the box is drawn with
66 % \dashbox[5cm][c]{dashed lines}.
67 % \item[]\hskip-\leftmargin
68 % \DescribeMacro{\lbox}
69 % |\lbox[|\textit{layers}|]{|\textit{text}|}| draws a
70 % \lbox{\fbox{stack of boxes}} around its contents, with the number
71 % of layers given by the first parameter (default 2).
72 % \item[]\hskip-\leftmargin
73 % \DescribeMacro{\dlbox}
74 % |\dlbox[|\textit{layers}|]{|\textit{text}|}| works like |\lbox|,
75 % but the boxes are drawn with \dlbox[2]{\dbox{dashed lines}}.
76 % \end{itemize}
77 %
78 % The following style parameters are available:
79 %
80 % \begin{itemize}
81 % \item[]\hskip-\leftmargin
82 % \DescribeMacro{\dashlength}
83 % |\dashlength| gives the length of a dash plus the following
84 % gap. The default is 6pt.
85 % \item[]\hskip-\leftmargin
86 % \DescribeMacro{\dashdash}
87 % |\dashdash| gives the length of a dash. The default is 3pt.
88 % \item[]\hskip-\leftmargin
89 % \DescribeMacro{\layersize}
90 % |\layersize| gives the protrusion of each layer below the previous
91 % one. The default is |\dashdash|.
92 % \end{itemize}
93 %
94 % The following standard parameters are also observed:
95 %
96 % \begin{itemize}
97 % \item[]\hskip-\leftmargin
98 % \DescribeMacro{\fboxrule}
99 % |\fboxrule| gives the width of the dashes.
100 % \item[]\hskip-\leftmargin
101 % \DescribeMacro{\fboxsep}
102 % |\fboxsep| gives the separation between the box and text inside it.
103 % \end{itemize}
104 % \StopEventually{}
105 %
106 %
107 % \section{Implementation}
108 %
109 % \subsection{Preliminaries}
110 %
111 % Make sure we've got what we need, and announce the package.
112 %
113 % \begin{macrocode}
114 %<*package>
115 \NeedsTeXFormat{LaTeX2e}
116 \ProvidesPackage{dashbox}
117 [2001/12/11 v1.14 Dashed and layered boxes]
118 \RequirePackage{calc}
119 \RequirePackage{ifthen}
120 % \end{macrocode}
121 %
122 % \subsection{Style parameters}
123 %
124 % Define and give the default values of the style parameters.
125 %
126 % \begin{macro}{\dashlength}
127 % \begin{macrocode}
128 \newlength{\dashlength} \setlength{\dashlength}{6pt}
129 % \end{macrocode}
130 % \end{macro}
131 % \begin{macro}{\dashdash}
132 % \begin{macrocode}
133 \newlength{\dashdash} \setlength{\dashdash}{3pt}
134 % \end{macrocode}
135 % \end{macro}
136 % \begin{macro}{\layersize}
137 % \begin{macrocode}
138 \newlength{\layersize} \setlength{\layersize}{\dashdash}
139 % \end{macrocode}
140 % \end{macro}
141 %
142 % \subsection{Dashes}
143 %
144 % We need two new commands for drawing horizontal and vertical dashes.
145 %
146 % \begin{macro}{\hd@shrule}
147 % |\hd@shrule| takes one argument, the rule's width. The thickness of
148 % the dash is given by |\fboxrule|.
149 %
150 % \begin{macrocode}
151 \newcommand{\hd@shrule}[1]{%
152 \hbox to #1%
153 {\vrule height \fboxrule width \dashdash%
154 \cleaders\hbox to \dashlength%
155 {\hfill\rule{\dashdash}{\fboxrule}\hfill}\hfill%
156 \ifthenelse{\lengthtest{#1 > 2\dashdash}}%
157 {\vrule height \fboxrule width \dashdash}{}%
158 }}
159 % \end{macrocode}
160 % \end{macro}
161 %
162 % \begin{macro}{\vd@shrule}
163 % |\vd@shrule| takes one argument, the rule's height. The thickness of
164 % the dash is given by |\fboxrule|.
165 %
166 % \begin{macrocode}
167 \newcommand{\vd@shrule}[1]{%
168 \vbox to #1%
169 {\hrule height \dashdash width \fboxrule%
170 \cleaders\vbox to \dashlength%
171 {\vfill\rule{\fboxrule}{\dashdash}\vfill}\vfill%
172 \ifthenelse{\lengthtest{#1 > 2\dashdash}}%
173 {\hrule height \dashdash width \fboxrule}{}%
174 }}
175 % \end{macrocode}
176 % \end{macro}
177 %
178 % \subsection{Dashed boxes}
179 %
180 % A private save box and some lengths are defined. |\d@ashedsavebox|
181 % is a box to hold the contents of a dashed box. |\d@shedboxwidth| is
182 % the box's width, and |\d@shedboxtotalheight| is the height plus the
183 % depth.
184 %
185 % \begin{macro}{\d@shedsavebox}
186 % \begin{macrocode}
187 \newsavebox{\d@shedsavebox}
188 % \end{macrocode}
189 % \end{macro}
190 % \begin{macro}{\d@shedboxwidth}
191 % \begin{macrocode}
192 \newlength{\d@shedboxwidth}
193 % \end{macrocode}
194 % \end{macro}
195 % \begin{macro}{\d@shedboxtotalheight}
196 % \begin{macrocode}
197 \newlength{\d@shedboxtotalheight}
198 % \end{macrocode}
199 % \end{macro}
200 %
201 % \begin{macro}{\m@kedashbox}
202 % |\m@kedashbox| is where the work is actually done. It puts the box
203 % together piece by piece. It requires |\d@shedboxwidth| to be set by
204 % its caller.
205 %
206 % \begin{macrocode}
207 \newcommand{\m@kedashbox}{%
208 % \end{macrocode}
209 %
210 % The height plus depth of the box is calculated.
211 %
212 % \begin{macrocode}
213 \setlength{\d@shedboxtotalheight}%
214 {\dp\d@shedsavebox+\ht\d@shedsavebox+\fboxsep*2+\fboxrule*2}%
215 % \end{macrocode}
216 %
217 % The box is raised an appropriate amount, and drawn in a |b|-aligned
218 % parbox.
219 %
220 % \begin{macrocode}
221 \raisebox{-\fboxrule-\fboxsep-\dp\d@shedsavebox}{%
222 \parbox[b]{\d@shedboxwidth}{%
223 % \end{macrocode}
224 %
225 % Inter-line and inter-paragraph skip are disabled.
226 %
227 % \begin{macrocode}
228 \offinterlineskip%
229 \parskip=0pt%
230 % \end{macrocode}
231 %
232 % The top line is drawn; the kern makes the left and right sides line
233 % up properly.
234 %
235 % \begin{macrocode}
236 \hd@shrule{\d@shedboxwidth}%
237 \kern-\fboxrule%
238 \par%
239 % \end{macrocode}
240 %
241 % The left-hand side is now drawn, in a parbox of the correct width.
242 %
243 % \begin{macrocode}
244 \parbox{\fboxrule}{\vd@shrule{\d@shedboxtotalheight}}%
245 % \end{macrocode}
246 %
247 % Now the inside of the box is set in a parbox, with |\fboxsep| space
248 % top and bottom. The kerns add |\fboxsep| space at the left and
249 % right.
250 %
251 % \begin{macrocode}
252 \kern\fboxsep%
253 \parbox{\wd\d@shedsavebox}%
254 {\vspace{\fboxsep}\usebox{\d@shedsavebox}\vspace{\fboxsep}}%
255 \kern\fboxsep%
256 % \end{macrocode}
257 %
258 % The right-hand side is drawn just like the left-hand side, and the
259 % bottom just like the top.
260 %
261 % \begin{macrocode}
262 \parbox{\fboxrule}{\vd@shrule{\d@shedboxtotalheight}}%
263 \par%
264 \kern-\fboxrule%
265 \hd@shrule{\d@shedboxwidth}}%
266 }}
267 % \end{macrocode}
268 % \end{macro}
269 %
270 % \begin{macro}{\dbox}
271 % |\dbox| is just a wrapper around |\m@kedashbox| which saves its
272 % argument and then calculates the width according to that of its
273 % argument.
274 %
275 % \begin{macrocode}
276 \newcommand{\dbox}[1]{%
277 \sbox{\d@shedsavebox}{#1}%
278 \setlength{\d@shedboxwidth}{\wd\d@shedsavebox+\fboxsep*2+\fboxrule*2}%
279 \m@kedashbox}
280 % \end{macrocode}
281 % \end{macro}
282 %
283 % \begin{macro}{\dashbox}
284 % The code for |\dashbox| is partly taken from that for |\framebox|.
285 % Depending on whether any optional arguments are given, it either
286 % simply calls |\dbox|, or sets the width to that given and does the
287 % typesetting via |\savebox| and |\m@kedashbox|.
288 %
289 % \begin{macrocode}
290 \def\dashbox{\@ifnextchar[\@dashbox\dbox}
291 \def\@dashbox[#1]{\@ifnextchar[{\@idashbox[#1]}{\@idashbox[#1][c]}}
292 \long\def\@idashbox[#1][#2]#3%
293 {\setlength{\d@shedboxwidth}{#1}%
294 \savebox{\d@shedsavebox}[#1-\fboxsep*2-\fboxrule*2][#2]{#3}%
295 \m@kedashbox}
296 % \end{macrocode}
297 % \end{macro}
298 %
299 % \subsection{Layers}
300 %
301 % Another series of private variables are required for layers:
302 % |\l@yersavebox| holds the text to be set in a layer,
303 % |\l@yerwidth| holds the total width of the layer,
304 % |\l@yerboxwidth| the width of the layer box,
305 % |\l@yertotalheight| the height plus depth of the layer.
306 % |\l@yerlineheight| the lift of the top right-hand line, and
307 % |\l@yervoffset| the lift of the layer below the baseline.
308 %
309 % \begin{macro}{\l@yersavebox}
310 % \begin{macrocode}
311 \newsavebox{\l@yersavebox}
312 % \end{macrocode}
313 % \end{macro}
314 % \begin{macro}{\l@yerwidth}
315 % \begin{macrocode}
316 \newlength{\l@yerwidth}
317 % \end{macrocode}
318 % \end{macro}
319 % \begin{macro}{\l@yerboxwidth}
320 % \begin{macrocode}
321 \newlength{\l@yerboxwidth}
322 % \end{macrocode}
323 % \end{macro}
324 % \begin{macro}{\l@yertotalheight}
325 % \begin{macrocode}
326 \newlength{\l@yertotalheight}
327 % \end{macrocode}
328 % \end{macro}
329 % \begin{macro}{\l@yerlineheight}
330 % \begin{macrocode}
331 \newlength{\l@yerlineheight}
332 % \end{macrocode}
333 % \end{macro}
334 % \begin{macro}{\l@yervoffset}
335 % \begin{macrocode}
336 \newlength{\l@yervoffset}
337 % \end{macrocode}
338 % \end{macro}
339 %
340 % \begin{macro}{\m@kelayer}
341 % |\m@kelayer| makes a solid layer.
342 %
343 % \begin{macrocode}
344 \newcommand{\m@kelayer}[1]{%
345 % \end{macrocode}
346 %
347 % The various lengths are calculated. The argument gives the number of
348 % the layer, i.e.\ how far down it should be offset from its contents
349 % as a multiple of |\layersize|.
350 %
351 % \begin{macrocode}
352 \setlength{\l@yertotalheight}%
353 {\dp\l@yersavebox+\ht\l@yersavebox+\layersize-#1\layersize}%
354 \setlength{\l@yerlineheight}%
355 {\ht\l@yersavebox-#1\layersize-\fboxrule}%
356 \setlength{\l@yervoffset}%
357 {-\layersize-\dp\l@yersavebox}%
358 \setlength{\l@yerboxwidth}%
359 {\wd\l@yersavebox+\layersize-#1\layersize}%
360 % \end{macrocode}
361 %
362 % The layer is set in a parbox of width |\l@yerwidth|.
363 %
364 % \begin{macrocode}
365 \parbox{\l@yerwidth}{%
366 % \end{macrocode}
367 %
368 % Inter-line and inter-paragraph spacing are turned off.
369 %
370 % \begin{macrocode}
371 \offinterlineskip%
372 \parskip=0pt%
373 % \end{macrocode}
374 %
375 % The contents of the layer is set first.
376 %
377 % \begin{macrocode}
378 \usebox{\l@yersavebox}%
379 % \end{macrocode}
380 %
381 % The extra ``corner'' is added on to the bottom right.
382 %
383 % \begin{macrocode}
384 \rule[\l@yerlineheight]{\layersize}{\fboxrule}%
385 \kern-\fboxrule%
386 \rule[\l@yervoffset]{\fboxrule}{\l@yertotalheight}%
387 \kern-\wd\l@yersavebox\kern-\layersize\kern#1\layersize
388 \rule[\l@yervoffset]{\fboxrule}{\layersize}%
389 \kern-\fboxrule
390 \rule[\l@yervoffset]{\l@yerboxwidth}{\fboxrule}%
391 }}
392 % \end{macrocode}
393 % \end{macro}
394 %
395 % \begin{macro}{\l@yer}
396 % |\l@yer| draws a layer. The first argument gives the number of the
397 % layer, and the second its contents.
398 %
399 % \begin{macrocode}
400 \newcommand{\l@yer}[2]{%
401 \sbox{\l@yersavebox}{#2}%
402 \setlength{\l@yerwidth}{\wd\l@yersavebox+\layersize}%
403 \m@kelayer{#1}}
404 % \end{macrocode}
405 % \end{macro}
406 %
407 % \begin{macro}{\m@kedashlayer}
408 % |\m@kedashlayer| makes a dashed layer. The code is the same as for
409 % |\m@kelayer| except for the dash commands.
410 %
411 % \begin{macrocode}
412 \newcommand{\m@kedashlayer}[1]{%
413 \setlength{\l@yertotalheight}%
414 {\dp\l@yersavebox+\ht\l@yersavebox+\layersize-#1\layersize}%
415 \setlength{\l@yerlineheight}{\ht\l@yersavebox-#1\layersize-\fboxrule}%
416 \setlength{\l@yervoffset}{-\layersize-\dp\l@yersavebox}%
417 \setlength{\l@yerboxwidth}%
418 {\wd\l@yersavebox+\layersize-#1\layersize}%
419 \parbox{\l@yerwidth}{%
420 \offinterlineskip%
421 \parskip=0pt%
422 \usebox{\l@yersavebox}%
423 \raisebox{\l@yerlineheight}{\hd@shrule{\layersize}}%
424 \kern-\fboxrule%
425 \raisebox{\l@yervoffset}%
426 {\parbox[b]{\fboxrule}{\vd@shrule{\l@yertotalheight}}}%
427 \kern-\wd\l@yersavebox\kern-\layersize\kern#1\layersize
428 \raisebox{\l@yervoffset}%
429 {\parbox[b]{\fboxrule}{\vd@shrule{\layersize}}}%
430 \kern-\fboxrule
431 \raisebox{\l@yervoffset}%
432 {\hd@shrule{\l@yerboxwidth}}%
433 }}
434 % \end{macrocoode}
435 % \end{macro}
436 %
437 % \begin{macro}{\dl@yer}
438 % |\dl@yer| draws a dashed layer, just like |\l@yer| draws a solid
439 % one.
440 %
441 % \begin{macrocode}
442 \newcommand{\dl@yer}[2]
443 {\sbox{\l@yersavebox}{#2}%
444 \setlength{\l@yerwidth}{\wd\l@yersavebox+\layersize}%
445 \m@kedashlayer{#1}}
446 % \end{macrocode}
447 % \end{macro}
448 %
449 % \subsection{Stacks}
450 %
451 % Finally, the commands for drawing a stack of layers.
452 %
453 % |l@yercount| counts the number of layers drawn by the stack drawing
454 % \begin{macro}{l@yercount}
455 % \begin{macrocode}
456 \newcounter{l@yercount}
457 % \end{macrocode}
458 % \end{macro}
459 %
460 % \begin{macro}{\l@yers}
461 % |\l@yers| draws a stack of layers; it is parametrized on the command
462 % used to draw a layer (third argument). The first argument is number
463 % of layers, and the second is the text to set. The layers are drawn
464 % in in a loop, using |\l@yersavebox| as an accumulator, and the
465 % result is typeset.
466 %
467 % \begin{macrocode}
468 \newcommand{\l@yers}[3]
469 {\setcounter{l@yercount}{1}%
470 \sbox{\l@yersavebox}{#2}%
471 \whiledo{\not\(\value{l@yercount} > #1\)}%
472 {\sbox{\l@yersavebox}%
473 {#3{\value{l@yercount}}{\usebox{\l@yersavebox}}}%
474 \stepcounter{l@yercount}}%
475 \usebox{\l@yersavebox}%
476 }
477 % \end{macrocode}
478 % \end{macro}
479 %
480 % |\lbox| and |\dlbox| are just wrappers for |\l@yers|. They both
481 % default to drawing two layers.
482 %
483 % \begin{macro}{\lbox}
484 % \begin{macrocode}
485 \newcommand{\lbox}[2][2]{%
486 \l@yers{#1}{#2}{\l@yer}}
487 % \end{macrocode}
488 % \end{macro}
489 % \begin{macro}{\dlbox}
490 % \begin{macrocode}
491 \newcommand{\dlbox}[2][2]{%
492 \l@yers{#1}{#2}{\dl@yer}}
493 %</package>
494 % \end{macrocode}
495 % \end{macro}
496 %
497 % \Finale
498 \endinput