Debian Codegraph @

texmf-dist/source/latex/ncctools/nccboxes.dtx

raw
1 % \iffalse
2 %%
3 %% File: nccboxes.dtx Copyright (C) 2002--2005 by Alexander I. Rozhenko
4 %%
5 %<package>\NeedsTeXFormat{LaTeX2e}
6 %<package>\ProvidesPackage{nccboxes}
7 %<package> [2005/02/07 v1.2 Additional Boxes (NCC)]
8 %
9 % \changes{v1.03}{2002/01/29}{This version is uploaded to CTAN}
10 % \changes{v1.04}{2002/03/20}{Internal changes in |\jvbox|}
11 % \changes{v1.04}{2002/03/20}{The |\jparbox| command introduced}
12 % \changes{v1.05}{2002/05/24}{Bug in |\jparbox| (incorrect width) fixed}
13 % \changes{v1.1}{2004/11/28}{Documentation was prepared}
14 % \changes{v1.2}{2005/02/07}{Add |\tc| command}
15 % \changes{v1.2}{2005/02/07}{Allow lengthes in the Strut parameter}
16 %
17 %<*driver>
18 \let\makeindex\relax
19 \documentclass{ltxdoc}
20 \usepackage{nccboxes}
21 \GetFileInfo{nccboxes.sty}
22 \begin{document}
23 \title{The \textsf{nccboxes} package\thanks{This file
24 has version number \fileversion, last
25 revised \filedate.}}
26 \author{Alexander I. Rozhenko\\[email protected]}
27 \date{\filedate}
28 \maketitle
29 \DocInput{nccboxes.dtx}
30 \end{document}
31 %</driver>
32 % \fi
33 %
34 % The package implement special boxes and struts from NCC-\LaTeX.
35 %
36 % \section{User Interface}
37 %
38 % \DescribeMacro{\jhbox}
39 % This macro specifies a horizontal box whose width is calculate
40 % using a prototype and alignment position is specified in the same manner
41 % as in the |\makebox| command. The syntax:
42 % \begin{quote}
43 % |\jhbox|\marg{prototype}\oarg{pos}\marg{text}
44 % \end{quote}
45 % Here \meta{prototype} is a text whose width will be the width of generated
46 % box, \meta{pos} is an alignment parameter (|l|, |c|, |r|, or |s|;
47 % default is |c|).
48 %
49 % \DescribeMacro{\jvbox}
50 % This macro specifies a horizontal box whose height, depth, and vertical
51 % alignment is calculated using a prototype. The syntax:
52 % \begin{quote}
53 % |\jvbox|\marg{prototype}\oarg{pos}\marg{text}
54 % \end{quote}
55 % The \meta{text} argument is vertically aligned with respect to the
56 % strut defined by the \meta{prototype} parameter. The optional
57 % \meta{pos} parameter defines an alignment position
58 % (|t|, |c|, or |b|; default is |c|). If |t| is used, the \meta{text} is
59 % raised in such a way that its height will be equal to the height of
60 % the prototype's strut. For the |b| case, the depths will be equal, and,
61 % for the |c| case, the \meta{text} is vertically centered with respect to
62 % the prototype's strut. The height and depth of the prepared box are
63 % calculated as a maximum between the corresponding parameters of the
64 % \meta{prototype} and the vertically adjusted \meta{text}.
65 %
66 % \DescribeMacro{\jparbox}
67 % This macro prepares a paragraph box of the required width and
68 % vertically aligns it with respect to the prototype just in the same manner
69 % as the |\jvbox|. The syntax:
70 % \begin{quote}
71 % |\jparbox|\marg{prototype}\oarg{pos}\marg{width}\marg{text}
72 % \end{quote}
73 % The \meta{prototype} and \meta{pos} parameters have the same meaning
74 % as described for |\jvbox|. The \meta{width} is the width
75 % of the paragraph box and the \meta{text} is the box content.\pagebreak
76 %
77 % \DescribeMacro{\addbox}
78 % This macro specifies a horizontal box whose height and depth are
79 % adjusted using the given values. The syntax:
80 % \begin{quote}
81 % |\addbox|\marg{height-adjust}\marg{depth-adjust}\marg{text}
82 % \end{quote}
83 % For example, |\addbox{.5ex}{.5ex}{text}| increases the height
84 % and depth of produced box on |0.5ex|.
85 %
86 % \DescribeMacro{\pbox}
87 % This macro implements a simple one-column table. The syntax:
88 % \begin{quote}
89 % |\pbox|\oarg{pos}\marg{body}
90 % \end{quote}
91 % The \meta{pos} parameter may consist of two letters defining
92 % a relative alignment of the table rows in the column
93 % (|l|, |c|, or |r|) and the vertical alignment of the whole table
94 % with respect to surrounding text (|t|, |c|, or |b|).
95 % Centering is the default alignment. The distance between
96 % table rows does not depend on the |\arraystretch| value.
97 %
98 % \DescribeMacro{\picbox}
99 % The |\picbox|\marg{body} macro is equivalent to
100 % \begin{quote}
101 % |\begin{picture}(0,0)(0,0)|\meta{body}|\end{picture}|.
102 % \end{quote}
103 %
104 % To prepare fancy tables, the following commands can be used:
105 %
106 % \DescribeMacro{\Strut}
107 % \DescribeMacro{\Strutletter}
108 % The |\Strut/|\meta{value}|/| command is a special strut whose
109 % height and depth are calculated from the strut prototype
110 % command |\Strutletter| (letter |A| by default) as follows:
111 % if \meta{value} is positive, the full height of the current
112 % |\strutbox| multiplied by the \meta{value} is added to the
113 % height of strut prototype, otherwise the depth of strut prototype
114 % increases with the modulus of \meta{value} multiplied
115 % by the full height of |\strutbox|. For example,
116 % |\Strut/1/| inserts a strut which height exceeds the height
117 % of the letter |A| from the current font on the interline distance.
118 % A natural length is also possible as a value of |\Strut|'s
119 % parameter. So, the |\Strut/2mm/| means a strut with the height
120 % exceeding the height of strut letter over 2~mm.
121 % The |\Strut| without parameter is equal to |\Strut/0/|.
122 % Spaces after the |\Strut| are ignored.
123 %
124 % \DescribeMacro{\tstrut}
125 % \DescribeMacro{\bstrut}
126 % \DescribeMacro{\tbstrut}
127 % \DescribeMacro{\Strutstretch}
128 % The |\tstrut|, |\bstrut|, and |\tbstrut| commands insert
129 % struts exceeding the height, depth, and both height and depth
130 % of the strut prototype |\Strutletter| by a special small amount.
131 % This amount is calculated in such a way that the full height
132 % of |\tbstrut| will be equal to 1.5 of full height of the
133 % current |\strutbox|. The stretch factor 1.5 is specified in
134 % the |\Strutstretch| command. These commands are used in tables
135 % to insert a space between a horizontal line and a table row.
136 % But if the height and depth of row contents exceeds the
137 % height and depth of inserted strut, the inserted strut will
138 % take no effect.
139 %
140 % \DescribeMacro{\cbox}
141 % The |\cbox/|\meta{value}|/|\oarg{pos}\marg{body} command
142 % prepares a box whose body is a one-column table. Its height and
143 % depth are enlarged using |\tstrut| at the beginning and
144 % |\bstrut| at the end of body. The horizontal alignment
145 % (|l|, |c|, or |r|) in the column and the vertical
146 % alignment (|t|, |c|, or |b|) are defined in the
147 % \meta{pos} parameter. Centered alignment is used by
148 % default. The resulting box is vertically aligned with
149 % respect to the |\Strut/|\meta{value}|/| using the
150 % |\jvbox| command. The |\cbox*| command does the same
151 % but vanishes the height and depth of the resulting box.
152 % The |\cbox| command is used in the headers of tables.
153 % Its star form is useful in cells having vertical spans.
154 %
155 % \DescribeMacro{\cboxstyle}
156 % The |\cboxstyle| specifies a style applied to all
157 % |\cbox| commands. It can set a font size, shape, color,
158 % etc. The default value of |\cboxstyle| is empty.
159 %
160 % We demonstrate the usage of struts and |\cbox| on the
161 % following example:
162 % \begin{center}\catcode`|=12
163 % \renewcommand\cboxstyle{\small\bf}
164 % \setlength{\tabcolsep}{10pt}
165 % \begin{tabular}{|l|c|c|c|}\hline
166 % \cbox*/-1.5/{Vertically\\spanned head} & \cbox{Simple head}
167 % &\multicolumn2{c|}{\cbox{Very long head\\of two lines}}\\\cline{2-4}
168 % &\cbox{subhead} &\cbox{subhead} &\cbox{subhead}\\\hline
169 % \Strut/1/ Text & field & field & field \\
170 % Text & field & field & field \\
171 % \bstrut Text & field & field & field \\\hline
172 % \end{tabular}
173 % \end{center}
174 % It was produced as follows:
175 % \begin{quote}
176 % |\begin{center}|\\
177 % | \renewcommand\cboxstyle{\small\bf}|\\
178 % | \setlength{\tabcolsep}{10pt}|\\
179 % \verb+ \begin{tabular}{|l|c|c|c|}\hline+\\
180 % | \cbox*/-1.5/{Vertically\\spanned head} & \cbox{Simple head}|\\
181 % \verb+ &\multicolumn2{c|}{\cbox{Very long head\\of two lines}}\\+\\
182 % | \cline{2-4}|\\
183 % | &\cbox{subhead} &\cbox{subhead} &\cbox{subhead}\\\hline|\\
184 % | \Strut/1/ Text & field & field & field \\|\\
185 % | Text & field & field & field \\|\\
186 % | \bstrut Text & field & field & field \\\hline|\\
187 % | \end{tabular}|\\
188 % |\end{center}|
189 % \end{quote}
190 %
191 % \DescribeMacro{\tc}
192 % To center a table field, the |\tc|\marg{field} command is introduced
193 % since version 1.2 of the package. It inserts |\hspace*{\fill}|
194 % before and after the \meta{field}.
195 %
196 % \StopEventually{}
197 %
198 % \section{The Implementation}
199 %
200 % \begin{macro}{\addbox}
201 % The implementation of
202 % |\addbox|\marg{height-adjust}\marg{depth-adjust}\marg{text}.
203 % We use the |\setlength| in calculations
204 % of box's height and depth for compatibility with the |calc|
205 % package.
206 % \begin{macrocode}
207 %<*package>
208 \newcommand*{\addbox}[3]{%
209 \@begin@tempboxa\hbox{#3}%
210 \setlength\@tempdima{#1}%
211 \advance\@tempdima \ht\@tempboxa
212 \ht\@tempboxa \@tempdima
213 \setlength\@tempdima{#2}%
214 \advance\@tempdima \dp\@tempboxa
215 \dp\@tempboxa \@tempdima
216 \leavevmode\box\@tempboxa
217 \@end@tempboxa
218 }
219 % \end{macrocode}
220 % \end{macro}
221 %
222 % \begin{macro}{\jhbox}
223 % The implementation of |\jhbox|\marg{prototype}\oarg{pos}\marg{text}
224 % is very simple:
225 % \begin{macrocode}
226 \newcommand*{\jhbox}[1]{\settowidth\@tempdima{#1}\makebox[\@tempdima]}
227 % \end{macrocode}
228 % \end{macro}
229 %
230 % \begin{macro}{\jvbox}
231 % The |\jvbox|\marg{prototype}\oarg{pos}\marg{text} is implemented
232 % as follows. We prepare a vertical strut
233 % in zero box using the \meta{prototype}. Then we vertically adjust the
234 % content of the |\jvbox| and put the strut and the adjusted box.
235 % \begin{macrocode}
236 \newcommand*{\jvbox}[1]{%
237 \setbox\z@\hbox{\color@begingroup#1\color@endgroup}%
238 \setbox\z@\hbox{\vrule \@width\z@ \@height\ht\z@ \@depth\dp\z@}%
239 \NCC@jvbox
240 }
241 \newcommand*{\NCC@jvbox}[2][]{%
242 \setbox\@tempboxa\hbox{\color@begingroup#2\color@endgroup}%
243 \let\m@t\vss \let\m@b\vss
244 \@tfor\@tempa :=#1\do {%
245 \expandafter\let\csname m@\@tempa\endcsname\relax}%
246 \@tempdima\ht\z@ \advance\@tempdima -\ht\@tempboxa
247 \ifx\m@t\relax \else
248 \@tempdimb\dp\@tempboxa \advance\@tempdimb -\dp\z@
249 \ifx\m@b\relax \@tempdima \@tempdimb \else
250 \advance\@tempdimb \@tempdima \@tempdima .5\@tempdimb
251 \fi
252 \fi
253 \leavevmode \box\z@ \raise\@tempdima\box\@tempboxa
254 }
255 % \end{macrocode}
256 % \end{macro}
257 %
258 % \begin{macro}{\jparbox}
259 % The implementation of
260 % |\jparbox|\marg{prototype}\oarg{pos}\marg{width}\marg{body}
261 % is based on |\jvbox|, but we prepare the
262 % \meta{body} in the vertical box.
263 % \begin{macrocode}
264 \newcommand*{\jparbox}[1]{%
265 \@ifnextchar[{\NCC@jparbox{#1}}{\NCC@jparbox{#1}[]}%
266 }
267 \long\def\NCC@jparbox#1[#2]#3#4{%
268 \@begin@tempboxa\vtop{\setlength\@tempdima{#3}%
269 \hsize\@tempdima\@parboxrestore#4\@@par}%
270 \setlength\@tempdima{#3}% vbox containing only display equations can
271 \wd\@tempboxa\@tempdima % have lesser width. We correct it here
272 \jvbox{#1}[#2]{\box\@tempboxa}%
273 \@end@tempboxa
274 }
275 % \end{macrocode}
276 % \end{macro}
277 %
278 % \begin{macro}{\pbox}
279 % Now we implement the |\pbox|\oarg{pos}\marg{body} command.
280 % It is a simple one-column table. The |\arraystretch|
281 % has no effect on it. The \meta{pos} is a combination of
282 % vertical (tbc) and horizontal (lcr) positions. For example,
283 % |lt| means left adjusted table with first line on the base line.
284 % \begin{macrocode}
285 \newcommand*{\pbox}[2][]{%
286 \let\m@l\hss \let\m@r\hss \let\m@t\vss \let\m@b\vss
287 \@tfor\@tempa:=#1\do{%
288 \expandafter\let\csname m@\@tempa\endcsname\relax%
289 }%
290 \leavevmode\hbox{\color@begingroup
291 $\ifx\m@t\relax \vtop \else\ifx\m@b\relax \vbox\else \vcenter\fi\fi
292 \bgroup \baselineskip\z@\lineskip\z@
293 \def\\{\strut\@stackcr}%
294 \halign{\m@l\ignorespaces ##\unskip\m@r\cr #2\strut\crcr}%
295 \egroup$\color@endgroup
296 }%
297 }
298 % \end{macrocode}
299 % \end{macro}
300 %
301 % \begin{macro}{\picbox}
302 % The |\picbox|\marg{body} command:
303 % \begin{macrocode}
304 \newcommand*{\picbox}[1]{%
305 \setbox\@tempboxa\hb@xt@\z@{\ignorespaces#1\hss}%
306 \ht\@tempboxa\z@\dp\@tempboxa\z@
307 \leavevmode\box\@tempboxa
308 }
309 % \end{macrocode}
310 % \end{macro}
311 %
312 % \begin{macro}{\Strutletter}
313 % \begin{macro}{\Strutstretch}
314 % Here we specify macros for preparing special struts.
315 % The |\Strutletter| is the prototype for special struts.
316 % The |\Strutstretch| is a stretch of line height in |\cbox|
317 % with respect to |\strut|. We prepare special struts in
318 % the |\NCC@strutbox|. The |\NCC@strutsep| is a half
319 % of difference between stretched |\strut| and the full height
320 % of the |\Strutletter|.
321 % \begin{macrocode}
322 \newcommand{\Strutletter}{A}
323 \newcommand{\Strutstretch}{1.5}
324 \newsavebox\NCC@strutbox
325 \newdimen\NCC@strutsep
326 % \end{macrocode}
327 % \end{macro}
328 % \end{macro}
329 %
330 % \begin{macro}{\NCC@setstrut}
331 % The |\NCC@setstrut|\marg{command}|/|\meta{value}|/|
332 % tests the sequence |/|\meta{value}|/|, prepares the specified
333 % strut in the |\NCC@strutbox|, calculates the |\NCC@strutsep|,
334 % and then calls the \meta{command}.
335 % The |/|\meta{value}|/| sequence is optional. If it is omitted,
336 % |/0/| is supposed.
337 % \begin{macrocode}
338 \def\NCC@setstrut#1{%
339 \setbox\NCC@strutbox\hbox{\vphantom{\Strutletter}}%
340 \@tempdima\ht\strutbox \advance\@tempdima\dp\strutbox
341 \NCC@strutsep \Strutstretch\@tempdima
342 \advance\NCC@strutsep -\ht\NCC@strutbox
343 \advance\NCC@strutsep -\dp\NCC@strutbox
344 \NCC@strutsep .5\NCC@strutsep
345 \@ifnextchar/{\NCC@setstrutn{#1}}{\NCC@setstrutl{#1}\z@}%
346 }
347 \def\NCC@setstrutn#1/#2/{\NCC@setstrutl{#1}{#2\@tempdima}}
348 \def\NCC@setstrutl#1#2{%
349 \@defaultunits\@tempdima#2\relax\@nnil
350 \ifdim\@tempdima>\z@
351 \advance\@tempdima \ht\NCC@strutbox
352 \ht\NCC@strutbox \@tempdima
353 \else
354 \@tempdima -\@tempdima
355 \advance\@tempdima \dp\NCC@strutbox
356 \dp\NCC@strutbox \@tempdima
357 \fi
358 #1%
359 }
360 % \end{macrocode}
361 % \end{macro}
362 %
363 % \begin{macro}{\Strut}
364 % Now we define the |\Strut/|\meta{value}|/|.
365 % It is quite simple:
366 % \begin{macrocode}
367 \newcommand{\Strut}{%
368 \NCC@setstrut{\leavevmode\copy\NCC@strutbox\ignorespaces}%
369 }
370 % \end{macrocode}
371 % \end{macro}
372 %
373 % \begin{macro}{\tstrut}
374 % \begin{macro}{\bstrut}
375 % \begin{macro}{\tbstrut}
376 % Next we define |\tstrut|, |\bstrut|, and |\tbstrut| via the |\addbox|
377 % command. All these struts use the |\NCC@setstrut| to calculate
378 % special strut parameters.
379 % \begin{macrocode}
380 \newcommand{\tstrut}{%
381 \NCC@setstrut{}\addbox\NCC@strutsep\z@{\copy\NCC@strutbox}%
382 }
383 \newcommand{\bstrut}{%
384 \NCC@setstrut{}\addbox\z@\NCC@strutsep{\copy\NCC@strutbox}%
385 }
386 \newcommand{\tbstrut}{%
387 \NCC@setstrut{}\addbox\NCC@strutsep\NCC@strutsep{\copy\NCC@strutbox}%
388 }
389 % \end{macrocode}
390 % \end{macro}
391 % \end{macro}
392 % \end{macro}
393 %
394 % \begin{macro}{\cbox}
395 % \begin{macro}{\cboxstyle}
396 % Now, we define the
397 % |\cbox/|\meta{value}|/|\oarg{pos}\marg{body} command and its
398 % star-form. It is useful in headers of tables. The |\cboxstyle| is
399 % a styling command applied to every |\cbox|.
400 % \begin{macrocode}
401 \newcommand{\cboxstyle}{}
402 \newcommand{\cbox}{%
403 \@ifstar{\def\@tempa{\ht\@tempboxa\z@ \dp\@tempboxa\z@}\NCC@xcbox}%
404 {\let\@tempa\relax\NCC@xcbox}%
405 }
406 \def\NCC@xcbox{%
407 \leavevmode \hbox\bgroup\color@begingroup
408 \cboxstyle\NCC@setstrut{\NCC@ycbox}%
409 }
410 \newcommand*{\NCC@ycbox}[2][]{%
411 \setbox\@tempboxa\hbox{%
412 \jvbox{\addbox\NCC@strutsep\NCC@strutsep{\copy\NCC@strutbox}}[#1]%
413 {\pbox[#1t]{\tstrut\ignorespaces #2\unskip\bstrut}}}%
414 \@tempa \box\@tempboxa
415 \color@endgroup\egroup
416 }
417 % \end{macrocode}
418 % \end{macro}
419 % \end{macro}
420 %
421 % \begin{macro}{\tc}
422 % And finally, we define the |\tc|\marg{field} command.
423 % \begin{macrocode}
424 \newcommand{\tc}[1]{\hspace*{\fill}#1\hspace*{\fill}}
425 %</package>
426 % \end{macrocode}
427 % \end{macro}
428 \endinput