Debian Codegraph @

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

raw
1 % \iffalse
2 % $Id: warpcol.dtx,v 1.4 1998/09/12 05:59:06 wayner Exp $
3 % 1998-06-08 Wayne A. Rochester
4 %
5 %%
6 %% This program can be redistributed and/or modified under the terms
7 %% of the LaTeX Project Public License Distributed from CTAN archives
8 %% in directory macros/latex/base/lppl.txt.
9 %%
10 %
11 % Doc-source file for use with LaTeX2e
12 %
13 % \fi
14 % \iffalse
15 %<*dtx>
16 \ProvidesFile{warpcol.dtx}
17 %</dtx>
18 %<package>\NeedsTeXFormat{LaTeX2e}
19 %<package>\ProvidesPackage{warpcol}
20 %<driver>\ProvidesFile{warpcol.drv}
21 % \fi
22 % \ProvidesFile{warpcol.dtx}
23 [2007/11/21 v1.0c Numerical column definition]
24 %
25 % \iffalse
26 %<*driver>
27 \documentclass{ltxdoc}
28 \usepackage{warpcol}
29 \begin{document}
30 \DocInput{warpcol.dtx}
31 \end{document}
32 %</driver>
33 % \fi
34 %
35 % \changes{v1.0a}{1998/06/08}{First release}
36 % \changes{v1.0b}{1998/09/12}{Prevented macro expansion during pattern scanning}
37 % \changes{v1.0c}{2007/11/21}{Add LPPL license statement (hv)}
38 %
39 % \MakeShortVerb{\|}
40 % \GetFileInfo{warpcol.dtx}
41 %
42 % \title{The |warpcol| package\thanks{This file has version number
43 % \fileversion, last revised \filedate\ for adding LPPL license statement.}}
44 % \author{W. A. Rochester}
45 % \maketitle
46 % \date{\filedate}
47 %
48 % \begin{abstract}
49 % This file defines a tabular column type for formatting numerical
50 % columns. The column type enables numerical items to be right justified
51 % relative to each other, while centred beneath the column label. In
52 % addition, macros are provided to enable variations on this column type
53 % to be defined.
54 % \end{abstract}
55 %
56 % \section{Introduction}
57 %
58 % The primary aim of this package is to provide a means to centre a
59 % tabular column label over a column of right-justified numbers.
60 % However, the package goes further to provide a general mechanism for
61 % justifying numerical items relative to each other and column labels.
62 % The package works by justifying each numerical item within a box whose
63 % width is specified by a `pattern'. The width is calculated as the
64 % width of the pattern after each number in the pattern is expanded to
65 % that number of zeros. For example, the pattern `$-3.2$' would be
66 % expanded to `$-000.00$'. Naturally, pattern width calculation and
67 % typesetting of numerical items are performed in math mode.
68 %
69 % The applications of this package overlap with those of David
70 % Carlisle's |dcolumn| package, which aligns numbers on their decimal
71 % points. However, the differing approaches of the packages create a
72 % number of differences in the ways they can be used. First, the
73 % |dcolumn| package can align items with varying numbers of decimal
74 % places. To achieve such alignment with this package, numbers must be
75 % padded with, for example, the active character |~|, redefined to print
76 % a space the width of a digit. Second, the present package can align
77 % items that are not simple numbers. Such items include negative
78 % numbers, which are not properly handled by the |dcolumn| package
79 % (but can be if the package is modified slightly).
80 %
81 % \section{Usage}
82 %
83 % The package defines the |P| column type for use with the most common
84 % application of the package: centring labels over right-justified
85 % numbers. This column type is used as follows:
86 %
87 % \begin{verbatim}
88 % \begin{tabular}{P{3.1}P{-2.1}} \hline\hline
89 % \multicolumn{1}{c}{Label 1} & \multicolumn{1}{c}{Label 2} \\ \hline
90 % 123.4 & -12.3 \\
91 % 12.3 & 12.3 \\
92 % 1.2 & 1.2 \\ \hline\hline
93 % \end{tabular}
94 % \end{verbatim}
95 %
96 % \noindent
97 % \begin{tabular}{P{3.1}P{-2.1}} \hline\hline
98 % \multicolumn{1}{c}{Label 1} & \multicolumn{1}{c}{Label 2} \\ \hline
99 % 123.4 & -12.3 \\
100 % 12.3 & 12.3 \\
101 % 1.2 & 1.2 \\ \hline\hline
102 % \end{tabular}
103 % \vspace{\baselineskip}
104 %
105 % The column labels must be set using the |\multicolumn| command to
106 % prevent them from being formatted with the |P| column type. Additional
107 % column types can be defined by the use of the |\pcolbegin| and
108 % |\pcolend| commands. The |\pcolbegin| command takes two arguments. The
109 % first is a code (l, c or r) specifying how numerical items should be
110 % justified relative to each other. The second is the pattern. The
111 % remaining examples make use of the following definitions (which are
112 % not included in the package):
113 %
114 % \begin{verbatim}
115 % \newcolumntype{L}[1]{>{\pcolbegin{r}{#1}}l<{\pcolend}}
116 % \newcolumntype{R}[1]{>{\pcolbegin{r}{#1}}r<{\pcolend}}
117 % \newcommand{\pcolhd}[1]{\multicolumn{1}{c}{#1}}
118 % \end{verbatim}
119 %
120 % \newcolumntype{L}[1]{>{\pcolbegin{r}{#1}}l<{\pcolend}}
121 % \newcolumntype{R}[1]{>{\pcolbegin{r}{#1}}r<{\pcolend}}
122 % \newcommand{\pcolhd}[1]{\multicolumn{1}{c}{#1}}
123 %
124 % Column labels are justified correctly regardless of whether they are
125 % shorter or longer than the numerical items:
126 %
127 % \begin{verbatim}
128 % \begin{tabular}{L{3.1}L{3.1}P{3.1}P{3.1}R{3.1}R{3.1}} \hline\hline
129 % \multicolumn{1}{l}{SL} & \multicolumn{1}{l}{Long label} &
130 % \multicolumn{1}{c}{SL} & \multicolumn{1}{c}{Long label} &
131 % \multicolumn{1}{r}{SL} & \multicolumn{1}{r}{Long label} \\ \hline
132 % 123.4 & 123.4 & 123.4 & 123.4 & 123.4 & 123.4 \\
133 % 12.3 & 12.3 & 12.3 & 12.3 & 12.3 & 12.3 \\
134 % 1.2 & 1.2 & 1.2 & 1.2 & 1.2 & 1.2 \\ \hline\hline
135 % \end{tabular}
136 % \end{verbatim}
137 %
138 % \noindent
139 % \begin{tabular}{L{3.1}L{3.1}P{3.1}P{3.1}R{3.1}R{3.1}} \hline\hline
140 % \multicolumn{1}{l}{SL} & \multicolumn{1}{l}{Long label} &
141 % \multicolumn{1}{c}{SL} & \multicolumn{1}{c}{Long label} &
142 % \multicolumn{1}{r}{SL} & \multicolumn{1}{r}{Long label} \\ \hline
143 % 123.4 & 123.4 & 123.4 & 123.4 & 123.4 & 123.4 \\
144 % 12.3 & 12.3 & 12.3 & 12.3 & 12.3 & 12.3 \\
145 % 1.2 & 1.2 & 1.2 & 1.2 & 1.2 & 1.2 \\ \hline\hline
146 % \end{tabular}
147 % \vspace{\baselineskip}
148 %
149 % Numerical items can be left justified, right justified or centred
150 % relative to column labels:
151 %
152 % \begin{verbatim}
153 % \begin{tabular}{L{3.1}R{3.1}P{3.1}} \hline\hline
154 % \pcolhd{Left justified} & \pcolhd{Right justified} & \pcolhd{Centred}
155 % \\ \hline
156 % 123.4 & 123.4 & 123.4 \\
157 % 12.3 & 12.3 & 12.3 \\
158 % 1.2 & 1.2 & 1.2 \\ \hline\hline
159 % \end{tabular}
160 % \end{verbatim}
161 %
162 % \noindent
163 % \begin{tabular}{L{3.1}R{3.1}P{3.1}} \hline\hline
164 % \pcolhd{Left justified} & \pcolhd{Right justified} & \pcolhd{Centred}
165 % \\ \hline
166 % 123.4 & 123.4 & 123.4 \\
167 % 12.3 & 12.3 & 12.3 \\
168 % 1.2 & 1.2 & 1.2 \\ \hline\hline
169 % \end{tabular}
170 % \vspace{\baselineskip}
171 %
172 % They can also be left justified, right justified or centred relative
173 % to each other:
174 %
175 % \begin{verbatim}
176 % \begin{tabular}{>{\pcolbegin{l}{3.1}}c<{\pcolend}P{3.1}%
177 % >{\pcolbegin{c}{3.1}}c<{\pcolend}} \hline\hline
178 % \pcolhd{Left justified} & \pcolhd{Right justified} & \pcolhd{Centred}
179 % \\ \hline
180 % 123.4 & 123.4 & 123.4 \\
181 % 12.3 & 12.3 & 12.3 \\
182 % 1.2 & 1.2 & 1.2 \\ \hline\hline
183 % \end{tabular}
184 % \end{verbatim}
185 %
186 % \noindent
187 % \begin{tabular}{>{\pcolbegin{l}{3.1}}c<{\pcolend}P{3.1}%
188 % >{\pcolbegin{c}{3.1}}c<{\pcolend}} \hline\hline
189 % \pcolhd{Left justified} & \pcolhd{Right justified} & \pcolhd{Centred}
190 % \\ \hline
191 % 123.4 & 123.4 & 123.4 \\
192 % 12.3 & 12.3 & 12.3 \\
193 % 1.2 & 1.2 & 1.2 \\ \hline\hline
194 % \end{tabular}
195 % \vspace{\baselineskip}
196 %
197 % Finally, here is an example with columns that contain something other
198 % than simple numbers:
199 %
200 % \begin{verbatim}
201 % \begin{tabular}{>{\pcolbegin{l}{< 1.3}}c<{\pcolend}P{3\,3.2}}
202 % \hline\hline
203 % \pcolhd{$p$} & \pcolhd{Cost (\$)} \\ \hline
204 % > 0.1 & 123\,456.78 \\
205 % < 0.1 & 23\,456.78 \\
206 % < 0.01 & 4\,523.45 \\
207 % < 0.001 & 345.67 \\ \hline\hline
208 % \end{tabular}
209 % \end{verbatim}
210 %
211 % \noindent
212 % \begin{tabular}{L{< 1.3}P{3\,3.2}}
213 % \hline\hline
214 % \pcolhd{$p$} & \pcolhd{Cost (\$)} \\ \hline
215 % > 0.1 & 123\,456.78 \\
216 % < 0.1 & 23\,456.78 \\
217 % < 0.01 & 4\,523.45 \\
218 % < 0.001 & 345.67 \\ \hline\hline
219 % \end{tabular}
220 % \vspace{\baselineskip}
221 %
222 % \section{Implementation}
223 %
224 % \begin{macrocode}
225 %<*package>
226 % \end{macrocode}
227 %
228 % Load the |array| package, if it is not already loaded.
229 % \begin{macrocode}
230 \RequirePackage{array}
231 % \end{macrocode}
232 %
233 % Declare counters and dimensions.
234 % \begin{macrocode}
235 \newcount\WPC@digcnt
236 \newbox\WPC@patbox
237 \newbox\WPC@valbox
238 % \end{macrocode}
239 %
240 % \begin{macro}{\WPC@digval}
241 % The |\WPC@digval| command prints the given character if the character is a
242 % digit, and `x' otherwise.
243 % \begin{macrocode}
244 \def\WPC@digval#1{%
245 \ifx#100%
246 \else\ifx#111%
247 \else\ifx#122%
248 \else\ifx#133%
249 \else\ifx#144%
250 \else\ifx#155%
251 \else\ifx#166%
252 \else\ifx#177%
253 \else\ifx#188%
254 \else\ifx#199%
255 \else x\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi}
256 % \end{macrocode}
257 % \end{macro}
258 %
259 % \begin{macro}{\WPC@digstr}
260 % The |\WPC@digstr| command prints a row of zeroes the length of the
261 % count in the |\WPC@digcnt| counter.
262 % \begin{macrocode}
263 \def\WPC@digstr{%
264 \loop 0\advance\WPC@digcnt by-1 \ifnum\WPC@digcnt>0 \repeat}
265 % \end{macrocode}
266 % \end{macro}
267 %
268 % \begin{macro}{\WPC@expandpat}
269 % The |\WPC@expandpat| command expands the given pattern, for example from
270 % $-3.2$ to $-000.00$.
271 % \begin{macrocode}
272 \def\WPC@expandpat#1{%
273 \ifx#1\end
274 \ifnum\WPC@digcnt>0 \WPC@digstr\fi
275 \let\WPC@next=\relax
276 \else
277 \edef\WPC@dv{\WPC@digval#1}%
278 \if x\WPC@dv
279 \ifnum\WPC@digcnt>0 \WPC@digstr\fi
280 #1%
281 \else
282 \multiply\WPC@digcnt by10 \advance\WPC@digcnt by\WPC@dv
283 \fi
284 \let\WPC@next=\WPC@expandpat
285 \fi
286 \WPC@next}
287 % \end{macrocode}
288 % \end{macro}
289 %
290 % \begin{macro}{\pcolbegin}
291 % The |\pcolbegin| command is executed before column entries. The first argument
292 % is the justification code (l, r or c), and the second is the pattern (e.g.\
293 % $-2.1$). The command begins the definition of a box containing the table item.
294 % The width of the box is set to the width of the expanded pattern. Fill
295 % commands justify the value within the box. The value is typeset in math mode.
296 % \begin{macrocode}
297 \def\pcolbegin#1#2{%
298 % \end{macrocode}
299 % Initialise the digit count and save the justification code.
300 % \begin{macrocode}
301 \WPC@digcnt=0
302 \edef\WPC@just{#1}%
303 % \end{macrocode}
304 % Create a box containing the expanded pattern (e.g.\ $-00.0$).
305 % \begin{macrocode}
306 \setbox\WPC@patbox=\hbox{$\WPC@expandpat#2\end$}%
307 % \end{macrocode}
308 % Begin the definition of the value box.
309 % \begin{macrocode}
310 \setbox\WPC@valbox=\hbox to\wd\WPC@patbox\bgroup
311 \if#1r\hfil\else\if#1c\hfil\fi\fi$}
312 % \end{macrocode}
313 % \end{macro}
314 %
315 % \begin{macro}{\pcolend}
316 % The |\pcolend| command is executed after column entries. It completes the box
317 % definition started by the |\pcolbegin| command, and then prints the box.
318 % \begin{macrocode}
319 \newcommand{\pcolend}{$%
320 \if l\WPC@just\hfil\else\if c\WPC@just\hfil\fi\fi
321 \egroup\box\WPC@valbox}
322 % \end{macrocode}
323 % \end{macro}
324 %
325 % \begin{macro}{P}
326 % Declare the |P| column type.
327 % \begin{macrocode}
328 \newcolumntype{P}[1]{>{\pcolbegin{r}{#1}}c<{\pcolend}}
329 % \end{macrocode}
330 % \end{macro}
331 %
332 % \begin{macrocode}
333 %</package>
334 % \end{macrocode}
335 %
336 % \DeleteShortVerb{\|}
337 \endinput