summaryrefslogtreecommitdiff
path: root/macros/generic/colortab/colortab-doc.tex
blob: a71f74da11332d79f94e35bb8e32a477ee0b5166 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
%% Documentation for colortab.tex/colortab.sty.
%%
%% The color commands \gray and \lightgray must be defined if you
%% want to see the examples. pstricks.tex will be loaded for this
%% purpose if it is found. Otherwise, you must load your own
%% color commands.
%%
%% Change these if using different size paper. You can also include the
%% twosided style option, if desired:

\documentclass[12pt]{article}
\usepackage [T1]{fontenc}
\usepackage{mathpazo,fancybox,url}
\usepackage{pstricks,colortab}
\let\CTfv\fileversion
\newgray{lightgray}{0.5}
\newgray{gray}{1}
\makeatletter
% VERBATIM HACKS:
\VerbatimFootnotes

% Short meta (works in verbatim. Can't use < for other purposes.
\catcode`\<=13 \def<#1>{{\rm\it #1\/}}    % <meta> (works in verbatim)

% Short verbatim. " can appear in verbatim environments.
\def\temp{\Verb"}
\expandafter\def\expandafter\dospecials\expandafter{\dospecials\do\"}
\catcode`\"=13
\let"\temp

\def\n#1{{\tt\string#1}}

% Verbatim item:
\newcommand\vitem{\SaveVerb[{\def\bf{}\item[\UseVerb{\MyTemp}]}]{\MyTemp}}

% Verbatim section"

% EXAMPLES:
% 1. Save example verbatim to \jobname.tmp,
% 2. Input verbatim with \catcode`\"=14 (" is a comment).
% 3. Input again with \catcode\`"=9 (" is ignored).

\renewcommand{\EveryVerbatimLine}[2]{}
\renewcommand{\EveryVerbOutLine}[2]{}
\newcommand\BeginExample{%
  \VerbatimEnvironment\begin{VerbatimOut}{\jobname.tmp}}
\newcommand\EndExample{%
  \end{VerbatimOut}%.
  \renewcommand{\EveryVerbatimLine}{}%
  \renewcommand{\EveryVerbatimCodes}{\catcode`\"=14}%
  \LVerbatimInput{\jobname.tmp}%
  \catcode`\"=9}

\iftrue% always using color
\newenvironment{example}{\BeginExample}{\EndExample
  \begin{center}\leavevmode\input{\jobname.tmp}\end{center}}
\else
\newenvironment{example}{\VerbatimEnvironment\LVerbatim}{\endLVerbatim}
\fi

% END PREAMBLE:
\makeatother
\title{Documentation\thanks{Documentation revised by Herbert Vo\ss} for colortab:\\[5pt]
  Shading and coloring \TeX\ tables, v. \CTfv}
\author{Timothy Van Zandt\\ \url{tvz@Princeton.EDU}}
\date{\today}

\begin{document}

\maketitle
\tableofcontents

\begin{quote}
"colortab.tex/colortab.sty" contains macros that let you use your color
commands for shading and coloring cells in tables and other alignment
environments. It is compatible with most \TeX\ macro packages.
\end{quote}

\section{Introduction}

Adding color to tables is fraught with difficulties, but as the examples in
this file indicate, it can be done. In any case, consider this an advanced
topic, and be aware that the commands in "colortab.tex" are not robust.

This is meant to supplement your own color commands. There are many macro
files that implement color for the various "dvi" drivers that can support
color. E.g., the PSTricks package works with a variety of DVI-to-PS drivers.

For example, suppose you have a macro that defines the color command "\gray".
"colortab.tex" requires that one of the following produce a gray line:
\begin{LVerbatim}
  {\gray \hrule}
  \gray{\hrule}
\end{LVerbatim}
if you want to use this command to color the cells in tables.
This is probably the case if the one of the following produces gray text:
\begin{LVerbatim}
  {\gray I am gray!}
  \gray{I am gray!}
\end{LVerbatim}

"colortab.tex" contains macros for \TeX's "\halign" primitive. Incorporating
color into high-level macros based on the "\halign" primitive requires a
case-by-case treatment. "colortab.tex" also contains macros for coloring cells
\LaTeX's various array environments, and for the \LaTeX\ "longtable"
environment that is defined in the "longtable" (or "longtabl") style option.
These can serve as examples that can be accommodated to other table macros.
See the code itself for happy hacking.

\section{\TeX's halign primitive}

To shade cells in an alignment, use
\begin{LVerbatim}
  \coloralign
\end{LVerbatim}
instead of "\halign". Then,  to color the columns in one or more rows, type
\begin{LVerbatim}
  \CC
    <row of colors>\cr
    <rows to be colored>\cr
  \ECC
\end{LVerbatim}
For example:
\begin{example}
  \setbox\strutbox=\hbox{\vrule height11.5pt
    depth6.5pt width0pt}%
  \vbox{\offinterlineskip
    \coloralign{%
        \vrule\strut\quad\hfil#\hfil\quad
        &\vrule\quad\hfil#\quad\vrule\cr
      \noalign{\hrule}%
      \CC
        \gray &\cr
        Tamarind&Chiplote\cr
      \ECC\noalign{\hrule}%
      \CC
        \lightgray &\gray\cr
        Lulu&Serrano\cr\noalign{\hrule}%
        Guanabana&Larga\cr
      \ECC\noalign{\hrule}%
  }}
\end{example}

"\CC" and "\ECC" stand for ``ColorCells'' and ``EndColorCells'', respectively.
You cannot change the name of "\ECC" with "\let" or "\def" (without redefining
"\CC"), because it is really just a delimiter. This is also true of the first
"\cr", which marks the end of the row of color commands.
Remember that only complete rows can go between "\CC" and "\ECC". Where you
include horizontal lines is generally inconsequential. You can have nested
"\coloralign" environments, but the nested environment must be enclosed in
brackets "{}".  There is no "\coloralign to" or "\coloralign spread" because
the space inserted by "\tabskip" won't be shaded.

These macros are not very robust. You can make best use of them by knowing how
they work. "\coloralign" just saves the preamble, and otherwise is identical
to "\halign". "\CC" finds the height of the rows that have to be colored, and
then "\CC" draws a rectangle using \TeX's line-drawing primitives in each
cell, colored by the color commands included in the first line that follows
"\CC". E.g.,
\begin{LVerbatim}
  \yellow &&\red \cr
\end{LVerbatim}
draws a yellow rectangle in column 1, nothing in column 2, and a red rectangle
in column 3. Then "\CC" goes back up the height of the rectangle, so that
\TeX's current point is back where it was when "\CC" started. At this point,
"\CC" has finished its work. When the next rows of the alignment environment
are processed by "\halign", they are put down on top of the rectangles, and
hence have colored backgrounds.

"\CC" finds the height of the rows to be colored by putting the rows into an
"\halign" environment, using the preamble that was saved by "\coloralign", and
then measuring the height of the resulting box.

\section{\LaTeX\ array environments}

Cells can be colored in a \LaTeX\ array without using a special array
environment (i.e., there is no \LaTeX\ analog to "\coloralign"). Use "\LCC"
instead of "\CC", and use "\\" to end the row of color commands instead of
"\cr". For example:
\begin{example}
  \def\arraystretch{1.5}%
  \begin{tabular}{|l|c|}\hline
    \LCC
      \gray & \\
      Tamarind & Chiplote \\ \hline
    \ECC
    \LCC
      \lightgray & \gray\\
      Lulu & Serrano\\ \hline
      Guanabana & Larga\\ \hline
    \ECC
  \end{tabular}
\end{example}
The same caveats apply as with the "\coloralign" environment.

When \n\LCC\ and \n\ECC\ are used with Frank Mittelbach's "array.sty", nested
array-type environments and "\multicolumn" commands wipe out information
needed by \n\ECC\. Here is a workaround: Put "\SP" (``SavePreamble'') at the
beginning of the array-type environment (right after the column declarations),
and put "\RP" (``RestorePreamble'') at the end of each line containing a
"\multicolumn" command or nested array-type environment (after the "\\", and
before the \n\ECC). For example:
\begin{LVerbatim}
  \begin{tabular}{|l|c|}\SP\hline
    \LCC
      \gray & \\
      \multicolumn{2}{c}{Tamarind}\\ \RP \hline
    \ECC
  \end{tabular}
\end{LVerbatim}
Further nesting (e.g., an array within a "\multicolumn", or a "\multicolumn"
or array within a nested array) sometimes works and sometimes doesn't. You
will have to figure that one out for yourself.


\section{longtable.sty}

"longtable.sty", by David Carlisle, defines the "longtable" environment, for
making multipage tables. "\LCC" will not work with "longtable". However,
"colortab" contains other macros that will work, if you use "longtable.sty" in
conjunction with Frank Mittelbach's "array.sty". These macros have been tested
only briefly, with version 3.04 of "longtable.sty" and version 2.1b of
"array.sty".

Before every column identifier in the environment's argument (e.g., "c", "l",
"r", "p", "m" or "b"), put
\begin{description}
  \vitem"!{\LC}" If none of the below applies;
  \vitem"!{\LCi}" If the column is preceded by one or more vertical lines;
  \vitem"!{\LCii}" If the column is followed by two vertical lines;
  \vitem"!{\LCiii}" If the column is preceded by one or more vertical lines
and followed by two vertical lines.
  \vitem"!{\LCz{<len1>}{<len2>}}" If "colortab" should back up by <len1>
before drawing the background, and should draw the background <len2> shorter
than the width of the column.
\end{description}
Remember that you have to do this for every column, not just the columns that
you want to color.

Then include
\begin{LVerbatim}
  \LColors <color> & <color> & ... & <color>\\
\end{LVerbatim}
in the first row of the environment, and later on as well if you wish to
change the colors. Here also you have to include every column, but you can
leave an entry blank if you don't want any background color in that column.

The color comes out right, or at all, only after you have run the file enough
times for "longtable.sty" to set the alignment correctly.

Here is an example. The output will appear in this documentation only if
"longtable.sty" or "longtabl.sty" is installed on your system.
\begingroup
  \makeatletter
  \catcode`\<=12
% Modification Denis GIROU (CNRS/IDRIS - France) - &lt;Denis.Girou@idris.fr&gt; - 10 Sep. 1996
% Can't work with LaTeX 2e
%  \@input{longtable.sty}%
%  \@input{longtabl.sty}%
%  \@input{array.sty}%
  \@input{longtable.styX}% Avoid loading of longtable.sty...
  \@input{longtabl.sty}%
  \@input{array.styX}% Avoid loading of array.sty...
  \@testtrue
  \@ifundefined{c@LT@tables}{\@testfalse}{}%
  \@ifundefined{d@llarbegin}{\@testfalse}{}%
  \if@test\else
    \renewenvironment{example}{\VerbatimEnvironment\LVerbatim}{\endLVerbatim}%
  \fi
  \makeatother
\begin{example}
  \LARGE
  \begin{longtable}{|!{\LCiii}l||!{\LCi}c|!{\LCi}c|}\hline
    \LColors \gray & & \\
      Tamarind & Chiplote & Galanga\\ \hline
    \LColors \lightgray & & \gray\\
      Lulu & & Serrano\\ \hline
      Guanabana & Larga &\\ \hline
  \end{longtable}
\end{example}
\endgroup

\section{Coloring lines}

Let's begin with the "\halign" environment. Changing the color of lines is
easy, because if you write, say, "{\gray\hrule}", then the line comes out
gray. For example:
\begin{example}
  % Thicker lines and wider spacing give better view:
  \setbox\strutbox=\hbox{%
    \vrule height15.5pt depth8.5pt width0pt}%
  \def\Hrule{\hrule height 2.5pt}%
  \def\Vrule{\vrule width 2.5pt}%
  % Now the table:
  \vbox{\offinterlineskip
    \halign{%
        {\lightgray\Vrule}\strut\quad\hfil#\hfil\quad
        &{\gray\Vrule}\quad\hfil#\quad\Vrule\cr
      \noalign{\Hrule}%
      Tamarind& Chiplote\cr\noalign{{\darkgray\Hrule}}%
      Lulu& Serrano\cr\noalign{\Hrule}%
      Guanabana& Larga\cr\noalign{{\lightgray\Hrule}}%
  }}
\end{example}

With \LaTeX, you can add an entry like
\begin{LVerbatim}
  @{\hspace{\tabcolsep}{\gray\vrule}\hspace{\tabcolsep}}
\end{LVerbatim}
to the argument of the alignment environment, instead of "|", if you want to
color the vertical line that is drawn. If using "array.sty", you can try:
\begin{LVerbatim}
  !{{\gray\vrule}}
\end{LVerbatim}

To color horizontal lines with \LaTeX, don't bother trying
\begin{LVerbatim}
  {\gray\hline}
\end{LVerbatim}
because it won't work. You write your own version of "\hline" and "\cline", or
use the non-aligned color commands described in the next section.

\section{Non-aligned color with PSTricks}

Here are a few other commands that can be useful for adding color to tables.
{\bf They only work with PSTricks, v0.93 or later.} <color> in this case is
the name of the color, without the backslash. These fudge the color commands
so that they do not have to be balanced with respect to \TeX\ grouping. You
can achieve the same thing using "\special{<raw postscript>}" and "\noalign",
if you know what you are doing. These should work with just about any
alignment macro, include "\halign" and \LaTeX's "tabular" environment.

\begin{description}

\vitem"\AC{<color>} ... \EAC" \

  These stand for "AlignColor" and "EndAlignColor", respectively. <color> is
the name of the color, without a backslash, rather than a color command. This
can be used within a cell, but they do not have to be within the same cell,
nor do they have to be properly nested with respect to \TeX\ grouping.
Generally, "\AC{<color>}" switches to <color>, and \n\EAC\ restores the color
that would be in effect if the first \n\AC\ command were missing.

\vitem"\NAC{<color>} ... \ENAC" \

  These stand for "NoAlignColor" and "EndNoAlignColor", respectively. These
are like \n\AC\ and \n\EAC, but the color commands are put inside a
"\noalign". They can only appear at the end of a line, after "\\" or "\cr".

\end{description}
Actually, these do not even have to be used in pairs.

Here is an example of how "\AC", etc., can be used. to color lines in \LaTeX\
arrays. The output will appear in this documentation only if PSTricks is
installed on your system:
\begingroup
\ifx\PSTricksLoaded\endinput\else
  \renewenvironment{example}{\VerbatimEnvironment\LVerbatim}{\endLVerbatim}
\fi
\begin{example}
  \arrayrulewidth 1.5pt
  \begin{tabular}{|l|c|}\hline
    Tamarind& Chiplote\\ \NAC{gray}\hline\ENAC
    Lulu& Serrano\\ \cline{1-1}
      \NAC{lightgray}\cline{2-2}\ENAC
    Guanabana\AC{lightgray} & \EAC Larga\\ \hline
  \end{tabular}
\end{example}
\endgroup

\end{document}
%% END colortab.doc