summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/context/manuals/reference/en/co-tabulate.tex
blob: cbd1a570d76c7a1eb216b3dccac82d19722046ae (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
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
\startcomponent co-tabulate

\environment contextref-env
\product contextref

\chapter[tabulate]{Tabulation}
\index{tabulation}
\index{tables+running text}
\macro{\tex{starttabulate}}
\macro{\tex{definetabulate}}
\macro{\tex{setuptabulate}}

The second mechanism for generating tabular information
is tabulation. We will see that the specification of
tabulations does not differ much from that of tables.

Tabular information can be found in the running text and the
location of that information is fixed (i.e. it is not allowed
to float like tables and figures).

The tabulation mechanism is meant for that tabular
information in which cells may contain information with more
that one paragraph. However the table and tabular mechanism
can be used indifferently we advise you to use them
consistently because the spacing within the both mechanisms
differ.

The table commands form a layer around \TABLE, but the
tabulation commands are written for \CONTEXT. The tabulation
mechanism uses the same interface when possible. As we do in
the table mechanism we use \type {\NC} as column separator
and \type {\NR} as row separator.

\startbuffer
\starttabulate[|l|c|r|]
\NC this and that \NC left and right \NC here and there \NC \NR
\NC low and high  \NC up and down    \NC back and forth \NC \NR
\stoptabulate
\stopbuffer

\typebuffer

\getbuffer

The three commands \type {l}, \type {c} and \type {r} stand for:

\starttabulate[|lT|p|]
\NC l \NC left align  \NC \NR
\NC c \NC center      \NC \NR
\NC r \NC right align \NC \NR
\stoptabulate

There are spacing commands. These relate to
one||line as well as multi||line (paragraphs) cells.

\starttabulate[|lT|p|]
\NC i\sl n \NC spacing left   \NC \NR
\NC j\sl n \NC spacing right  \NC \NR
\NC k\sl n \NC spacing around \NC \NR
\stoptabulate

The factor {\ttsl n} is applied to the unit of spacing which
is default set at .5em (see \type {\setuptabulate}).

\startbuffer
\starttabulate[|l|k2c|r|]
\NC this and that \NC left and right \NC here and there \NC \NR
\NC low and high  \NC up and down    \NC back and forth \NC \NR
\stoptabulate
\stopbuffer

\typebuffer

\getbuffer

The width of a column is set with:

\startbuffer
\starttabulate[|lw(4cm)|w(4cm)l|r|]
\NC this and that \NC left and right \NC here and there \NC \NR
\NC low and high  \NC up and down    \NC back and forth \NC \NR
\stoptabulate
\stopbuffer

\typebuffer

\getbuffer

The most important reason for developing the tabulation
mechanism lies in the fast that we wanted to be able to type
set multi paragraph columns. A prerequisite was that we
should be able to use the full width of the text body. This
option is supported by:

\starttabulate[|lT|p|]
\NC w({\sl d}) \NC 1 line,   fixed width    \NC \NR
\NC p({\sl d}) \NC paragraph, fixed width   \NC \NR
\NC p          \NC paragraph, maximum width \NC \NR
\stoptabulate

In the next example the first column has an unknown width.
The second column contains a left aligned paragraph with a
width of 4~cm. The third column has a width of 2~cm and
consists of one line. The last column contains a paragraph
that occupies the remaining width.

\starttyping
\starttabulate[|l|p(4cm)l|w(2cm)|p|]
...
\stoptabulate
\stoptyping

A four column table with four paragraphs is specified with:

\starttyping
\starttabulate[|p|p|p|p|]
...
\stoptabulate
\stoptyping

In stead of specifying a body font in each cell we can
specify them per column. In the next tabulation the
definition is \type {[|lT|p|]}.

\starttabulate[|lT|p|]
\NC B \NC \bf boldface \NC \NR
\NC I \NC \it italic   \NC \NR
\NC R \NC \sl roman    \NC \NR
\NC S \NC \sl slanted  \NC \NR
\NC T \NC \tt teletype \NC \NR
\stoptabulate

Math is possible with:

\starttabulate[|lT|p|]
\NC m \NC in||line math \NC \NR
\NC M \NC display  math \NC \NR
\stoptabulate

With the letter \type {f} we can specify a body font, like
\type {f\bs}. There are also the following commands:

\starttabulate[|lT|p|]
\NC f\tex{command} \NC font specification                \NC \NR
\NC b\arg{..}      \NC place \type{..} before the entry  \NC \NR
\NC a\arg{..}      \NC place \type{..} after the entry   \NC \NR
\NC h\tex{command} \NC apply  \tex{command} on the entry \NC \NR
\stoptabulate

The \type{h}||command (hook) allows some tricks like:

\startbuffer
\starttabulate[|w(2cm)h\inframed|b{(}a{)}|p|]
\HC {Uggly}     \NC isn't it?       \NC he says.     \NC \NR
\HC {Beautiful} \NC but meaningless \NC I would say. \NC \NR
\stoptabulate
\stopbuffer

\typebuffer

Because we use \type {\inframed} the frame remains within the
line. The command applies only to the cells that are
preceded by \type {\HC}. The \arg{} are important because
\type {\inframed} expects these.

\getbuffer

We can use \type {h} for alternative situations, like:

\startbuffer
\unexpanded\def\SmallDash#1{\blackrule[width=#1em]}
\starttabulate[|l|lh\SmallDash|]
\HL
\NC \bf item \NC \bf number \NC \NR
\HL
\NC figures  \HC  {5}       \NC \NR
\NC tables   \HC  {8}       \NC \NR
\NC formulas \HC {12}       \NC \NR
\HL
\stoptabulate
\stopbuffer

\getbuffer

All three cells are adapted. Do not forget the \arg{} in
the column with the numbers!

\typebuffer

We used \type {\NC} as a column separator but an alternative
is \type {\EQ} that places a specified character.

\startbuffer
\starttabulate
\NC =||sign      \EQ a separator can be specified by altering the
                     variable \type {EQ} \NC \NR
\NC :||character \EQ default a colon is used but an equal sign
                     is a reasonable alternative \NC \NR
\stoptabulate
\stopbuffer

\typebuffer

This results in:

\getbuffer

We saw \type {\NC} for normal cell entries, \type {\EQ} for
entries separated by a character and \type {\HC} for entries
that are influenced by a command. There is also \type
{\HQ} for a cell entry with a separator and a command. When
no formatting is needed there are the commands: \type {\RC}
and \type {\RQ}.

\startbuffer
\starttabulate[|*{4}{cBh\type|}]
\NC     separator \NC normal \NC raw   \NC command \NC \NR
\RC \bf yes       \HC {\EQ}  \HC {\RQ} \HC {\HQ}   \NC \NR
\RC \bf no        \HC {\NC}  \HC {\RC} \HC {\HC}   \NC \NR
\stoptabulate
\stopbuffer

\getbuffer

This small tabulation shows all three alternatives. Here we
have a tabulation with four centered columns, {\bf boldface}
or \type {verbatim}, of which two cells have a different
alignment. The table is coded as:

\typebuffer

The equal sign or any other character can be forced with the
\type {e}~command in the definition.

\starttabulate[|lT|p|]
\NC e \NC sets a symbol in front of the next column \NC \NR
\stoptabulate

When several columns have an equal specification we can
combine those specifications. Note that the number
of~\type{|} must be correct.

\startbuffer
\starttabulate[|*{3}{k1pc|}]
\NC this and that \NC left and right \NC here and there \NC \NR
\NC low and high  \NC up and down    \NC back and forth \NC \NR
\stoptabulate
\stopbuffer

\typebuffer

Here we typed $1+3\times1=4$ times a \type{|}.

\getbuffer

A better example of the automatic cell width determination
is the next one.

\startbuffer
\starttabulate[|l|p|]
\NC tables     \NC We use \type {\starttable} when we typeset tables
                   but the exact location is not fixed and the
                   information is allowed to float in the running
                   text. \NC \NR
\NC tabulation \NC The command \type {\starttabulate} is meant for
                   tabular information that is part of the running text.
                   The automatic calculation of the cell width
                   is a feature in this mechanism. \NC \NR
\stoptabulate
\stopbuffer

\getbuffer


This tabulation was typed as:

\typebuffer

When no tabulation is specified it is assumed that
\type{[|l|p|]} is wanted. To prevent typing the same
specification all over again you can use the tabulation
format definition command:

\startbuffer
\definetabulate[Three][|lB|lS|p|]

\startThree
\NC one \NC two  \NC three four five six seven eight nine ten eleven
                     twelve thirteen fourteen fifteen and so on \NC \NR
\stopThree
\stopbuffer

\typebuffer

\getbuffer

The tabulation commands can be summarized with:

\showsetup{definetabulate}

The first argument gives the tabulation a logical name. The
second argument is optional and specifies the associated
tabulations; later on we will give an example. The last
argument specifies the cells.

Then we have:

\showsetup{starttabulate}

In this command the first argument specifies the cells, the
second and optional argument the set up.

\showsetup{setuptabulate}

The optional argument specifies the associated tabulations.
When the parameter \type {indenting} is set at \type {yes},
the width of the tabulations will adapt to the actual
indent. In case of a \type {\start ... \stopnarrower}
environment the left and right indent are taken into
account. The parameter \type {unit} is used for the
spacing commands~\type {i}, \type {j} and~\type {k}. The
commands specified after the parameter \type {inner} are
applied just in front of the first row and are effective in
the whole tabulation.

The possibilities for framing tabulations are limited. You
can add horizontal lines with \type {\HL}. This command takes
care of the vertical spacing as the next example
illustrates:

\startbuffer
\starttabulate[|l|p|]
\HL
\NC small  \NC They say, small is beautiful.        \NC \NR
\HL
\NC medium \NC It seems that medium is the message. \NC \NR
\HL
\NC large  \NC Large T||shirts are always sold out. \NC \NR
\HL
\stoptabulate
\stopbuffer

\typebuffer

When a pagebreak occurs in the middle of a tabulation the
horizontal line is repeated automatically. Vertical spacing
can be set by \type {\FL}, \type {\ML} and \type {\LL}.
These commands stand for {\em first}, {\em middle} and {\em
last line}.

\getbuffer

The spacing around the lines is related to the depth of a line.

\starttyping
\setuptabulate[distance={depth,medium}]
\stoptyping

There are different ways to adapt this set up, like:

\starttyping
\setuptabulate[distance=none]
\setuptabulate[distance=big]
\setuptabulate[distance={blank,small}]
\setuptabulate[distance={1ex,medium}]
\setuptabulate[distance=1cm]
\stoptyping

Tabulation is meant for the running text but it can also be
used in a floating block. In that case the spacing around
tabulation is suppressed. In the running text the actual
whitespace and textwidth are taken into account.

\startbuffer
\starttabulate
\NC You see? \NC As we can expect the width of a paragraph is adapted
                 to the width of the text. And you can even put an
                 itemize in such a cell.
                 \startitemize[packed]
                 \item like this
                 \item or that
                 \stopitemize \NC \NR
\stoptabulate
\stopbuffer

\startitemize

\item  This means that a tabulation within an itemization
       is adapted to the indent.

\getbuffer

\item  This little table was defined like this:

\typebuffer

\stopitemize

We can use and abuse tabulations to obtain some special
effects. Vice versa common effects can be combined quite
well with tabulations. The next, somewhat strange example
will illustrate that.

\startbuffer
\starttabulate[|p(2cm)|p(4cm)|p|]
\NC \startitemize[n,packed]
    \item first \item second \item third
    \stopitemize
\NC \startitemize[packed][items=5,width=4em,distance=.5em]
    \its this or that \its so and so \its here or there
    \stopitemize
\NC \startitemize[g,packed,broad]
    \item alpha \item beta \item gamma
    \stopitemize
\NC\NR
\stoptabulate
\stopbuffer

\getbuffer

In these kind of situations we should set the itemization
with the key \type {packed}.

\typebuffer

The content of a tabulation has some limitations, because
\TEX\ first reads the complete table. These limitations
relate to the macros that use \type {\catcode} adaptations.
In normal situations you will not notice these limitations,
only when you have typeset \TEX\ input with \TEX.

While discussing tables we already saw a financial table.
These kind of tables can best be set with the tabulation
commands.

\startbuffer
\starttabulate[|l|r|]
\NC not so much   \NC          1.220  \NC \NR
\NC somewhat more \NC          5.186  \NC \NR
\NC together      \NC \overbar{6.406} \NC \NR
\stoptabulate
\stopbuffer

\getbuffer

This tabulation was typed like this:

\typebuffer

As soon as we work with numbers there are several ways of
alignment. Like in tables we can make use of~\type {~}, but
we have to indicate the meaning of \type {~} explicitly.
This is caused by the fact that we still want to use
the~\type {~} within paragraphs as an non||hyphenatable space.

\starttyping
\starttabulate[|l|~c|]
\NC this is less \NC ~12 \NC \NR
\NC than that    \NC 185 \NC \NR
\stoptabulate
\stoptyping

We return to the defining of categories of tabulations.
An application of this option can be found in the commands
that make up a legend with a formula.

\starttyping
\definetabulate [legend]       [|emj1|i1|mR|]
\definetabulate [legend] [two] [|emj1|emk1|i1|mR|]
\setuptabulate  [legend]       [unit=.75em,EQ={=}]
\stoptyping

After these definitions that are default in \CONTEXT\ we can
type:

\startbuffer
\startlegend
\NC w \NC the width of a box  \NC pt \NR
\NC h \NC the height of a box \NC pt \NR
\NC d \NC the depth of a box  \NC pt \NR
\stoplegend
\stopbuffer

\typebuffer

This very simple legend becomes this:

\getbuffer

An extra entry is possible when we add the key \type {two}:

\startbuffer
\startlegend[two]
\NC w \NC width  \NC the width of a box  \NC pt \NR
\NC h \NC height \NC the height of a box \NC pt \NR
\NC d \NC depth  \NC de depth of a box   \NC pt \NR
\stoplegend
\stopbuffer

\typebuffer

This related tabulation inherits the set up of the original.
We also could have defined \type {\startlegendtwo}, but the
mentioned definition origins from the older functionality
that was part of earlier \CONTEXT\ versions.

\getbuffer

In a similar way the commands for typesetting facts are
defined.

\starttyping
\definetabulate [fact] [|R|ecmj1|i1mR|]
\setuptabulate  [fact] [unit=.75em,EQ={=}]
\stoptyping

The first column is set in roman and the next column is
separated by an equal sign. That second column is centered
and is set in math mode. That column also has some more
whitespace. The last column is also set in math mode but the
characters are set in roman. Some whitespace is added.

\startbuffer
\startfact
\NC width  \NC w \NC 48pt \NR
\NC height \NC h \NC  9pt \NR
\NC depth  \NC d \NC  3pt \NR
\stopfact
\stopbuffer

\typebuffer

This results in:

\getbuffer

In reality we also give a value to \type {inner} and then
specifications as below are possible:

\starttyping
\startfact
\\ width  \\ w \\ 48pt \\
\\ height \\ h \\  9pt \\
\\ depth  \\ d \\  3pt \\
\stopfact
\stoptyping

We want to conclude with an example of an automatic
calculation of the width of a paragraph. This command shows
|<|and we already saw that in other examples|>| that the
last \type {\NC} is redundant.

\startbuffer
\starttabulate[|Bl|p|Bl|]
\NC Read Me \NC \input tufte \NC Edward Tufte \NR
\stoptabulate
\stopbuffer

\typebuffer

\getbuffer

As was said earlier \CONTEXT\ takes care of adequate page
breaking in the middle of a tabulation. When we set \type
{\tracetabulatetrue} red lines are drawn in positions where
breaking is not allowed.

\startbuffer
\starttabulate[|c|p|p|]
\NC \bf Alpha \NC \bf Beta    \NC \bf Gamma              \NC\NR
\NC 1         \NC right indeed    \NC definitely wrong   \NC\NR
\NC 2         \NC \thinrules[n=3] \NC \thinrules[n=3]    \NC\NR
\NC 3         \NC oh yes          \NC simply no          \NC\NR
\NC 4         \NC very true       \NC as false as can be \NC\NR
\NC 5         \NC \thinrules[n=5] \NC \thinrules[n=5]    \NC\NR
\NC 6         \NC \thinrules[n=3] \NC \thinrules[n=4]    \NC\NR
\stoptabulate
\stopbuffer

\typebuffer {\tracetabulatetrue\getbuffer}

\startbuffer
\starttabulate[|c|p|p|]
\NC \bf Alpha \NC \bf Beta        \NC \bf Gamma          \NC\NR
\NC 1         \NC right indeed    \NC definitely wrong   \NC\NR
\NC 2         \NC oh yes          \NC simply no          \NC\NR
\NC 3         \NC very true       \NC as false as can be \NC\NR
\NC 4         \NC the whole truth \NC but the truth      \NC\NR
\stoptabulate
\stopbuffer

\typebuffer {\tracetabulatetrue\getbuffer}

\stopcomponent