| blob | 81f2f474c74a98f87e66e8f3149111be49f9888d |
1 % \iffalse meta-comment
2 %
3 % Copyright 1993-2014
4 %
5 % The LaTeX3 Project and any individual authors listed elsewhere
6 % in this file.
7 %
8 % This file is part of the Standard LaTeX `Tools Bundle'.
9 % -------------------------------------------------------
10 %
11 % It may be distributed and/or modified under the
12 % conditions of the LaTeX Project Public License, either version 1.3c
13 % of this license or (at your option) any later version.
14 % The latest version of this license is in
15 % http://www.latex-project.org/lppl.txt
16 % and version 1.3c or later is part of all distributions of LaTeX
17 % version 2005/12/01 or later.
18 %
19 % The list of all files belonging to the LaTeX `Tools Bundle' is
20 % given in the file `manifest.txt'.
21 %
22 % \fi
23 % \iffalse
24 %% File: dcolumn.dtx Copyright (C) 1992-1996 1999-2001 David Carlisle
25 %
26 %<*dtx>
27 \ProvidesFile{dcolumn.dtx}
28 %</dtx>
29 %<package>\NeedsTeXFormat{LaTeX2e}
30 %<package>\ProvidesPackage{dcolumn}
31 %<driver>\ProvidesFile{dcolumn.drv}
32 % \fi
33 % \ProvidesFile{dcolumn.dtx}
34 [2014/10/28 v1.06 decimal alignment package (DPC)]
35 %
36 % \iffalse
37 %<*driver>
38 \documentclass{ltxdoc}
39 \usepackage{dcolumn}
40 \DeleteShortVerb{\|}
41 \begin{document}
42 \DocInput{dcolumn.dtx}
43 \end{document}
44 %</driver>
45 % \fi
46 %
47 % \GetFileInfo{dcolumn.dtx}
48 %
49 % \title{The \textsf{dcolumn} package\thanks{This file
50 % has version number \fileversion, last
51 % revised \filedate.}}
52 % \author{David Carlisle}
53 % \date{\filedate}
54 % \author{David Carlisle}
55 % \MaintainedByLaTeXTeam{tools}
56 % \maketitle
57 %
58 %
59 % \changes{v1.00}{1992/02/17}{Initial version}
60 % \changes{v1.01}{1992/06/12}{Re-issue for the new doc and docstrip.}
61 % \changes{v1.02}{1994/03/14}{Re-issue for LaTeX2e}
62 % \changes{v1.03}{1996/02/28}{New feature, after tools/2093}
63 % \changes{v1.05}{1999/07/05}
64 % {Minor doc changes latex/3058}
65 % \changes{v1.06}{2001/05/28}
66 % {More doc changes (suggested by BNB, done by CAR) latex/3315}
67 %
68 % \CheckSum{143}
69 %
70 %
71 % \begin{abstract}
72 % This package defines a system for defining columns of entries in an
73 % \texttt{array} or \texttt{tabular} which are to be aligned on a
74 % `decimal point'.
75 % \end{abstract}
76 %
77 % \MakeShortVerb{\"}
78 %
79 % This package defines {\tt D} to be a column specifier with three
80 % arguments.\\
81 % "D{"\meta{sep.tex}"}{"\meta{sep.dvi}"}{"\meta{decimal
82 % places}"}"
83 %
84 % \meta{sep.tex} should be a single character, this is used as the
85 % separator in the {\tt .tex} file. Thus it will usually be `{\tt.}' or
86 % `{\tt,}'.
87 %
88 % \mbox{\meta{sep.dvi}} is used as the separator in the output, this may
89 % be the same as the first argument, but may be any math-mode
90 % expression, such as "\cdot". It should be noted that \texttt{dcolumn}
91 % always uses math mode for the digits as well as the separator.
92 %
93 % \meta{decimal places} should be the maximum number of decimal places
94 % in the column. If this is negative, any number of decimal places can
95 % be used in the column, and all entries will be centred on
96 % (the leading edge of) the
97 % separator. Note that this can cause a column to be too wide, compare
98 % the first two columns in the example below. If this argument is
99 % positive, the column uses macros equivalent to "\rightdots"
100 % "\endrightdots" of {\tt array.sty}, otherwise the macros are
101 % essentially equivalent to "\centerdots" "\endcenterdots".
102 %
103 % You may not want to use all three entries in the {\tt array} or {\tt
104 % tabular} preamble, so you may define your own preamble specifiers
105 % using "\newcolumntype".
106 %
107 % For example we may say:
108 %
109 % \noindent"\newcolumntype{d}[1]{D{.}{\cdot}{#1}}"
110 %
111 % {\tt d} takes a single argument specifying the number of decimal
112 % places, and the {\tt .tex} file should use {\tt.}, with $\cdot$ being
113 % used in the output.
114 %
115 % \noindent"\newcolumntype{.}{D{.}{.}{-1}}"
116 %
117 % {\tt .} specifies a column of entries to be centred on the~$.$.
118 %
119 % \noindent"\newcolumntype{,}{D{,}{,}{2}}"
120 %
121 % {\tt ,} specifies takes a column of entries with at most two decimal
122 % places after a~$,$.
123 %
124 % \newcolumntype{d}[1]{D{.}{\cdot}{#1}}
125 % \newcolumntype{.}{D{.}{.}{-1}}
126 % \newcolumntype{,}{D{,}{,}{2}}
127 %
128 % The following table begins "\begin{tabular}{|d{-1}|d{2}|.|,|}"
129 %
130 % \begin{center}
131 % \begin{tabular}{|d{-1}|d{2}|.|,|}
132 % 1.2 & 1.2 &1.2 &1,2 \\
133 % 1.23 & 1.23 &12.5 &300,2 \\
134 % 1121.2& 1121.2&861.20 &674,29 \\
135 % 184 & 184 &10 &69 \\
136 % .4 & .4 & &,4 \\
137 % & &.4 &
138 % \end{tabular}
139 % \end{center}
140 %
141 % Note that the first column, which had a negative \meta{decimal places}
142 % argument is wider than the second column, so that the decimal point
143 % appears in the middle of the column.
144 % Also note that this package deals correctly with entries with no
145 % decimal part, no integer part, and blank entries.
146 %
147 % If you have table headings (inserted with "\multicolumn{1}{c}{..}"
148 % to over-ride the "D" column type) then it may be that neither of the
149 % above `centred' or `right aligned' forms is quite what you want.
150 % \begin{center}\small
151 % \begin{tabular}[t]{|D..{-1}|D..{1}|D..{5.1}|}
152 %\multicolumn{1}{|c|}{head}&
153 %\multicolumn{1}{c|}{head}&
154 %\multicolumn{1}{c|}{head}\\[3pt]
155 % 1.2 & 1.2 &1.2 \\
156 % 11212.2& 11212.2&11212.2 \\
157 % .4 & .4 &.4
158 % \end{tabular}
159 % \hfill
160 % \begin{tabular}[t]{|D..{-1}|D..{1}|D..{1.1}|}
161 %\multicolumn{1}{|c|}{wide heading}&
162 %\multicolumn{1}{c|}{wide heading}&
163 %\multicolumn{1}{c|}{wide heading}\\[3pt]
164 % 1.2 & 1.2 &1.2 \\
165 % .4 & .4 &.4
166 % \end{tabular}
167 % \end{center}
168 %
169 % In both of these tables the first column is set with "D{.}{.}{-1}"
170 % to produce a column centered on the ".", and the second column is
171 % set with "D{.}{.}{1}" to produce a right aligned column.
172 %
173 % The centered column produces columns that are wider than necessary
174 % to fit in the numbers under a heading as it has to ensure that the
175 % decimal point is centred. The right aligned column two does not have
176 % this drawback, but under a wide heading a column of small right
177 % aligned figures looks a bit odd.
178 %
179 % In version v1.03 a third possibility is introduced. The third
180 % \meta{decimal places} argument may specify \emph{both} the number of
181 % digits to the left and to the right of the decimal place. The third
182 % column in the first table above is set with "D{.}{.}{5.1}" and in the
183 % second table, "D{.}{.}{1.1}", to specify
184 % `five places to the left and one to the right' and `one place to the
185 % left and% one to the right' respectively. (You may use `,' or other
186 % tokens, not necessarily `.' in this argument.) The column of figures
187 % is then positioned such that a number with the specified numbers of
188 % digits is centred in the column.
189 %
190 % This notation also enables columns that are centred on the mid-point
191 % of the separator, rather than its leading edge; for example
192 % "D{+}{\,\pm\,}{3,3}" will give nice, symmetric layout of up to three
193 % digits on either side of a $\pm$ sign.
194 %
195 % \StopEventually{}
196 %
197 %
198 % \section{The Macros}
199 %
200 % \begin{macrocode}
201 %<*package>
202 % \end{macrocode}
203 %
204 % First we load {\tt array.sty} if it not already loaded.
205 % \begin{macrocode}
206 \RequirePackage{array}
207 % \end{macrocode}
208 %
209 % The basic ideas behind these macros are explained in the documentation
210 % for {\tt array.sty}. However they use three
211 % tricks which may be useful in other contexts.
212 % \begin{itemize}
213 % \item The separator is surrounded in extra "{ }", so that it is set
214 % with "\mathord" spacing, otherwise, for instance a `,' would have
215 % extra space after it.
216 % \item The separator is not given its special definition by making it
217 % active, as this would not work for an entry such as "& .5 &", as the
218 % first token of an alignment entry is read {\em before\/} the preamble
219 % part, in case it is an "\omit", in which case the preamble is to be
220 % omitted. Instead we switch the mathcode to (hex) 8000, which makes the
221 % token act as if it were active.
222 % \item Although \verb|\mathcode`.="8000| makes {\tt.} act as if it
223 % were active, it is still not allowed in constructions such as
224 % "\def.{}", even in math-mode, so we have to construct an active
225 % version of the separator, this is done by making it the uppercase of
226 % "~", and then using the construct\\
227 % "\uppercase{\def~}{"\meta{definition}"}".\\
228 % Note that the \meta{definition} is not uppercased, so the definition
229 % can refer to the standard, non-active use of the separator.
230 % \end{itemize}
231 %
232 % \begin{macro}{\DC@}
233 % \changes{v1.03}{1996/02/28}{New feature, after tools/2093}
234 % Set up uppercase tables as required, and then grab the first part of
235 % the numerical argument into "\count@".
236 % \begin{macrocode}
237 \def\DC@#1#2#3{%
238 \uccode`\~=`#1\relax
239 \m@th
240 \afterassignment\DC@x\count@#3\relax{#1}{#2}}
241 % \end{macrocode}
242 % \end{macro}
243 %
244 % \begin{macro}{\DC@x}
245 % \changes{v1.03}{1996/02/28}{Macro added}
246 % If "\count@" is negative, centre on the decimal point. If it is
247 % positive either "#1" will be empty in which case bad out decimal
248 % part to the number of digits specified by "\count@" or (new feature
249 % in v1.03) it is none empty in which case "\count@" contains the
250 % number of digits to the left of the point, and "#1" contains a junk
251 % token (probably ".") followed by the number of digits to the right
252 % of the point. In either of these latter cases, "\DC@right" is used.
253 % \begin{macrocode}
254 \def\DC@x#1\relax#2#3{%
255 \ifnum\z@>\count@
256 \expandafter\DC@centre
257 \else
258 \expandafter\DC@right
259 \fi
260 {#2}{#3}{#1}}
261 % \end{macrocode}
262 % \end{macro}
263 %
264 % \begin{macro}{\DC@centre}
265 % If centering on the decimal point, just need to box up the two halves.
266 % \begin{macrocode}
267 \def\DC@centre#1#2#3{%
268 \let\DC@end\DC@endcentre
269 \uppercase{\def~}{$\egroup\setbox\tw@=\hbox\bgroup${#2}}%
270 \setbox\tw@=\hbox{${\phantom{{#2}}}$}%
271 \setbox\z@=\hbox\bgroup$\mathcode`#1="8000 }
272 % \end{macrocode}
273 % \end{macro}
274 %
275 % \begin{macro}{\DC@endcentre}
276 % and then pad out the smaller of the two boxes so there is the same
277 % amount of stuff either side of the point.
278 % \begin{macrocode}
279 \def\DC@endcentre{$\egroup
280 \ifdim \wd\z@>\wd\tw@
281 \setbox\tw@=\hbox to\wd\z@{\unhbox\tw@\hfill}%
282 \else
283 \setbox\z@=\hbox to\wd\tw@{\hfill\unhbox\z@}\fi
284 \box\z@\box\tw@}
285 % \end{macrocode}
286 % \end{macro}
287 %
288 % \begin{macro}{\DC@right}
289 % \changes{v1.03}{1996/02/28}{Re-implemented, after tools/2093}
290 % This deals with both the cases where a specified number of decimal
291 % places is given.
292 % \begin{macrocode}
293 \def\DC@right#1#2#3{%
294 \ifx\relax#3\relax
295 % \end{macrocode}
296 % If "#3" is empty, add "\hfill" to right align the column, and
297 % Just set "\DC@rl" to begin a group, so nothing fancy is done with
298 % the whole number part.
299 % \begin{macrocode}
300 \hfill
301 \let\DC@rl\bgroup
302 \else
303 % \end{macrocode}
304 % Otherwise set "\DC@rl" so that the whole number part is put in a
305 % box "\count@" times as wide as a digit.
306 % In order to share code with the other branch, then move "#3" (the
307 % number of decimal places) into "\count@" throwing away the `.' from
308 % the user syntax.
309 % \changes{v1.04}{1996/09/23}{Add \cs{hfill} so integer part
310 % is still flush right if no decimal point used.}
311 % \begin{macrocode}
312 \edef\DC@rl{to\the\count@\dimen@ii\bgroup\hss\hfill}%
313 \count@\@gobble#3\relax
314 \fi
315 % \end{macrocode}
316 %
317 % \begin{macrocode}
318 \let\DC@end\DC@endright
319 % \end{macrocode}
320 % Box 2 contains the decimal part, set to "\dimen@" which is
321 % calculated below to be "\count@" times the width of a digit, plus
322 % the with of the `decimal point'.
323 % \begin{macrocode}
324 \uppercase{\def~}{$\egroup\setbox\tw@\hbox to\dimen@\bgroup${#2}}%
325 \setbox\z@\hbox{$1$}\dimen@ii\wd\z@
326 \dimen@\count@\dimen@ii
327 \setbox\z@\hbox{${#2}$}\advance\dimen@\wd\z@
328 \setbox\tw@\hbox to\dimen@{}%
329 % \end{macrocode}
330 % Box 0 contains the whole number part, either just at its natural
331 % size for right aligned columns, or set to (the old value of)
332 % "\count@" times the width of a digit. "\DC@rl" defined above
333 % determines the two cases.
334 % \begin{macrocode}
335 \setbox\z@\hbox\DC@rl$\mathcode`#1="8000 }
336 % \end{macrocode}
337 % \end{macro}
338 %
339 % \begin{macro}{\DC@endright}
340 % \changes{v1.03}{1996/02/28}{Re-implemented, after tools/2093}
341 % Just finish off the second box, and then put out both boxes.
342 % \begin{macrocode}
343 \def\DC@endright{$\hfil\egroup\box\z@\box\tw@}
344 % \end{macrocode}
345 % \end{macro}
346 %
347 % \begin{macro}{D}
348 % The user interface, define the {\tt D} column to take three arguments.
349 % For special purposes, you may need to directly access "\DC@" rather
350 % than the "D" column, eg to get a bold version you could use
351 %\begin{verbatim}
352 % \newcolumntype{E}[3]{>{\boldmath\DC@{#1}{#2}{#3}}c<{\DC@end}}
353 %\end{verbatim}
354 % \begin{macrocode}
355 \newcolumntype{D}[3]{>{\DC@{#1}{#2}{#3}}c<{\DC@end}}
356 %</package>
357 % \end{macrocode}
358 % \end{macro}
359 %
360 %
361 % \Finale
362 \endinput