Debian Codegraph @

texmf-dist/source/latex/cals/decor.dtx

raw
1 % \section{Decorations}
2
3 % How much decoration requires a table? Initially I thought to implement
4 % a generic approach, so an user could extend the set of what is
5 % possible---for example, a dashed border instead of a solid one.
6 % But this is a hard task for me, therefore I switched back
7 % to the fixed set of properties. Indeed, the use case for cals
8 % tables is technical documentation, not a wanna-be designer showcases.
9 %
10 % The fixed set of decoration properties:
11 % \begin{itemize}
12 % \item padding
13 % \item border thickness
14 % \item cancelled after some thinking: border color
15 % \item cell background
16 % \end{itemize}
17 %
18 % In the first version of this package, decorations could be defined
19 % for all cells in a row, for all cells in a column and finally
20 % specially for a cell. Unfortunately, this approach does not work
21 % for borders of multipage tables, when the decorations on a break are
22 % different to the internal decorations. Trying different
23 % workarounds, I finally found a descriptive and direct approach:
24 % define default decorations for a cell plus define
25 % decorations for the table frame.
26 %
27 % How to decorate the common border of two cells? The following
28 % seems reasonable:
29 % \begin{itemize}
30 % \item The priority of settings: from the user, from the table
31 % frame, default. If cells have different priorities, use the
32 % highest one.
33 % \item When priorities are the same, use the maximal thinkness.
34 % \end{itemize}
35 %
36 % Imagine that the user uses only default decorations. Then all
37 % the internal vertical borders are the same, and all internal
38 % horizontal border are also the same. It took me time to
39 % understand this obvious thing, that for the default setup
40 % we need to define settings only for vertical and horizontal
41 % borders, not for all four borders.
42 %
43 % Column separation and row separation are two very different
44 % creatures. The former is fixed after a row is processed,
45 % the latter could change somewhen later due to a table break.
46
47 % \subsection{Setters and getters}
48
49 % No more setter and getters provided to discourage cell formatting.
50 % At the moment, if you really need it, use the knowledge of
51 % the internal variables.
52
53 % \begin{macro}{\cals@cs@width}
54 % Width of column separators (vertical borders). For all the widths, |0pt| disables the rule.
55 % \begin{macro}{\cals@framecs@width}
56 % Width of the left and right table frame border.
57 % \begin{macro}{\cals@rs@width}
58 % Width of row separators (horizontal borders).
59 % \begin{macro}{\cals@framers@width}
60 % Width of the top and bottom table frame border.
61 % \begin{macro}{\cals@bodyrs@width}
62 % Width of row separators between the body and the header or the footer.
63 % \begin{macro}{\cals@bgcolor}
64 % Background color of the cells. If the macro is empty, it means no background.
65 % \begin{macrocode}
66 \newcommand\cals@cs@width{.4pt}
67 \newcommand\cals@framecs@width{0pt}
68 \newcommand\cals@rs@width{.4pt}
69 \newcommand\cals@framers@width{0pt}
70 \newcommand\cals@bodyrs@width{1.2pt}
71 \newcommand\cals@bgcolor{}
72 % \end{macrocode}
73 % \end{macro}
74 % \end{macro}
75 % \end{macro}
76 % \end{macro}
77 % \end{macro}
78 % \end{macro}
79
80 % \begin{macro}{\cals@borderL}
81 % \begin{macro}{\cals@borderT}
82 % \begin{macro}{\cals@borderR}
83 % \begin{macro}{\cals@borderB}
84 % Overrides for the widths of the cell borders (left, top, right or bottom).
85 % Macros, set to |\relax| by the |calstable| environment.
86 % \end{macro}
87 % \end{macro}
88 % \end{macro}
89 % \end{macro}
90
91 % Padding parameters (|\cals@paddingL| etc) and related
92 % macros (|\alignC| etc) are defined near the macro |\cell|.
93
94 % \subsection{Decorations for a row}
95
96 % The whole code in this section is devoted to provide functionality
97 % for the functions |\cals@decor@begin|, |...@next|, |...@end|. After a row is ended,
98 % we have the following decorations:
99 % \begin{itemize}
100 % \item column separation: box |\cals@current@cs|
101 % \item rowsep specification for the top: macro |\cals@rs@above|
102 % \item rowsep specification for the bottom: macro |\cals@rs@below|
103 % \end{itemize}
104 % The high-level approach is obvious: we construct the decorations
105 % cell-by-cell. First, we calculate column separation, getting
106 % the width of the left and the right border. Then we use these
107 % values to update the border above and below. Unfortunately,
108 % there is a lot of small details. For example, as explained later,
109 % we construct the decorations with a delay, therefore the end-function
110 % is just a special sort of the next-function.
111
112 % \begin{macro}{\cals@decor@begin}
113 % Initialization.
114 % \begin{macrocode}
115 \newcommand\cals@decor@begin{\cals@csrow@begin\cals@rs@spec@begin}
116 % \end{macrocode}
117 % \end{macro}
118
119 % \begin{macro}{\cals@decor@next}
120 % Updates the decorations. The argument is the width of the cell.
121 % \begin{macrocode}
122 \newcommand\cals@decor@next[1]{%
123 \cals@csrow@nextcell{#1}\cals@borderL\cals@borderR\cals@bgcolor
124 \cals@rs@spec@next{#1}\cals@lastLeftWidth\cals@borderT\cals@borderB}
125 % \end{macrocode}
126 % \end{macro}
127
128 % \begin{macro}{\cals@decor@end}
129 % Finishes the decorations. Uses |\cals@lastLeftWidth|,
130 % which is the width of the last right border.
131 % \begin{macrocode}
132 \newcommand\cals@decor@end{%
133 \cals@csrow@end
134 \cals@rs@spec@end\cals@lastLeftWidth}
135 % \end{macrocode}
136 % \end{macro}
137
138 % \subsection{Deciding on the width and color}
139
140 % \begin{macro}{\cals@widthII}
141 % \begin{macro}{\cals@withWidthII}
142 % Calculate a final width from the default one (argument 1)
143 % and user-specified (argument 2, |\relax| means use the default),
144 % put it to the macro |\cals@width|. Also, the macro |withWidthII|
145 % start a conditional construction,
146 % true branch is executed when the width is not zero.
147 % Unused \#3 is for if-fi balancing, see |\cals@iftrue|.
148 % \begin{macrocode}
149 \newcommand\cals@widthII[2]{%
150 \ifx \relax#2\edef\cals@width{#1}%
151 \else \edef\cals@width{#2}\fi}
152
153 \newcommand\cals@withWidthII[3]{%
154 \cals@widthII{#1}{#2}%
155 \ifdim \cals@width>0pt }
156 % \end{macrocode}
157 % \end{macro}
158 % \end{macro}
159
160 % \begin{macro}{\cals@withColorII}
161 % Calculate a final color from the default one (argument 1)
162 % and user-specified (argument 2, |\relax| means use the default),
163 % set the macro |\cals@color| to it. The both arguments must
164 % be macro names, not token lists. Start a conditional
165 % construction, true branch is executed when the color name is
166 % given (not empty).
167 % Unused \#3 is for if-fi balancing, see |\cals@iftrue|.
168 % \begin{macrocode}
169 \newcommand\cals@withColorII[3]{%
170 \ifx \relax#2\edef\cals@color{#1}%
171 \else \edef\cals@color{#2}\fi
172 % \end{macrocode}
173 % Reversing a condition. Based on |\ifnot| macro by David Kastrup
174 % posted to comp.text.tex 2 March 1998, Message-ID:
175 % |<[email protected]>#1/1|.
176 % \begin{macrocode}
177 \ifx \cals@color\empty \else\expandafter\expandafter\fi\iffalse\iftrue\fi}
178 % \end{macrocode}
179 % \end{macro}
180
181 % \begin{macro}{\cals@halfWidthToDimen}
182 % Puts the half of the width in |#2| to the dimension
183 % register |#1|.
184 % \begin{macrocode}
185 \newcommand\cals@halfWidthToDimen[2]{%
186 \dimen#1=#2\relax \divide\dimen#1 by 2 }
187 % \end{macrocode}
188 % \end{macro}
189
190 % \begin{macro}{\cals@maxWidth}
191 % Of two widths, given as macros, selects the maximal and put
192 % the result to |\cals@width|. Takes care for |\relax|.
193 % \begin{macrocode}
194 \newcommand\cals@maxWidth[2]{%
195 \ifx \relax#1\relax
196 \ifx \relax#2\let\cals@width=\relax
197 \else \edef\cals@width{#2}\fi
198 \else
199 \ifx \relax#2\relax
200 \edef\cals@width{#1}%
201 \else
202 \ifdim #1>#2 \edef\cals@width{#1}%
203 \else \edef\cals@width{#2}\fi\fi\fi}
204 % \end{macrocode}
205 % \end{macro}
206
207 % \begin{macro}{\cals@iftrue}
208 % \begin{macro}{\cals@iffalse}
209 % Balancing if-fi. The following does not work:
210 % \begin{verbatim}
211 % \let\next=\iftrue ...
212 % \if ... \next ... \fi ... \fi
213 % \end{verbatim}
214 % But this code does work:
215 % \begin{verbatim}
216 % \let\next=\cals@iftrue ...
217 % \if ... \next\iftrue ... \fi ... \fi
218 % \end{verbatim}
219 % We use |\iftrue| (or any other if-start), which is taken into
220 % account when scanning for the fi-else-if balance,
221 % but ignored when executed.
222 % \begin{macrocode}
223 \def\cals@iftrue#1{\iftrue}
224 \def\cals@iffalse#1{\iffalse}
225 % \end{macrocode}
226 % \end{macro}
227 % \end{macro}