summaryrefslogtreecommitdiff
path: root/info/laan/pwt/pwt.tls
blob: 62a1be684060cb0d6314603b2caccf4b1d0a7e2a (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
\input blue.tex \loadindexmacros \report

\bluechapter Tools

\beginsummary
BLUe's format comprises tools.dat, a database of tools,
available at your fingertips,  which doesn't hinder when not needed.
\endsummary

At the moment tools.dat, the database of tools, contains macros for
typesetting
bridge, 
crosswords, 
the tower of hanoi game, 
creation of an index (and in there sorting macros),
ntglogo, 
Pascal, and
xyz-axes.
Most likely this database will grow.

\bluehead Use

Nobody would be surprised to hear that the ease of use of a tool
has all to do with the tool's jargon as implemented by its author.
However, how to access the tool is also important, and we would
love a uniform approach to that, wouldn't we?
Alas, consistency  at the outer level\Dash how the tools can be
accessed from the database tools.dat\Dash is too heavy a demand, 
as can be seen from the index tool in relation with the other tools.
The tools are just too varied. ^^{database,\ tools.dat}

\bluesubhead Adding a tool

First we have to decide what it is that we like to add. 
A format? A picture? Or just a tool? 
I had to add the \cs{xyz} picture to tools.dat, because it is not a format
and it does not obey the syntax of pic.dat entries, although
it looks like a picture in print to me.\ftn{Remember that the entries 
  in the address.dat, lit.dat, and pic.dat database obey the syntax 
  |\lst\<name>{| |<replacement text>}|.}

The entries of fmt.dat and tools.dat obey the syntax ^^{entry\ for\ tools.dat}
\begincenterverbatim
\tool\<name>fmt               \tool\<name>tool
...                  or       ...
\endinput                     \endinput
!endcenterverbatim


To ^{add\ a\ tool} the following has to be done.
\bitem separate the storage-allocating
       control sequences from the tool,
       i.e., treat \cs{newtoks} and the like separately
\bitem add the storage-allocating control sequences to \bluetex 
\bitem add the tool as a definition to tools.dat
\bitem add a load macro to \bluetex.
\smallbreak
\blueexample Add xyz macro to tools.dat

Suppose we wish to use the \cs{xyz} macro (with three arguments).
What to do?
The use could simply be \cs{loadxyz}, followed by the invocation
|\xyz{...}{...}{...}|. 

In order to make this possible, I have added to tools.dat
\begincenterverbatim
\tool\xyztool
\def\xyz#1#2#3{%the macro
...}
\endinput
!endcenterverbatim
and to  \bluetex
\begincenterverbatim
\def\loadxyz{\let\xyztool=x
   \loadtool
   \let\xyztool\undefined}
!endcenterverbatim
Confusing, isn't it?

\blueexample Add an environment to tools.dat

Suppose we wish to make use of the environment
\begincenterverbatim
\begin<yourtoolname>
...
\end<yourtoolname>
!endcenterverbatim
In order to make this possible we have to do several things.
First, add to tools.dat the following `file'
\begincenterverbatim
\tool\<yourtoolname>tool%Opening
<themacros>
\endinput               %Closing
!endcenterverbatim
Second, include in \bluetex{} the environment opening and closing,
next to the needed allocations
\thisverbatim{\catcode`\|=12 
              \catcode`\!=12
              \catcode`\~=0 
              }
\begincenterverbatim
%Tool environment macro
\def\begin<yourtoolname>{\begingroup
   \let\end<yourtoolname>\endgroup
   \let\<yourtoolname>tool=x
   \loadtool
}
%storage allocation
\new<type>\<name> 
%<type> is   box count dimen fam 
%            insert language skip
%            muskip read toks write
etc.
~endcenterverbatim
Fourth, verify the data integrity. (See later.)

There are a few restrictions on the macros, as a consequence
of the skipping technique used, i.e.,
via \TeX's argument-reading mechanism.
\bitem no outer defs, i.e, \cs{newtoks} and the like, should
       be declared in regular \bluetex
\bitem no \cs{par}, use \cs{endgraf}, or |\csname par\endcsname|.
\smallbreak
Remarks.
The restriction with respect to your outer defs can be circumvented by 
\bitem defining all macros non-outer, or 
\bitem using |\csname newtoks\endcsname\<tag>|, or 
\bitem extending \cs{unouterdefs} by your outer defs, i.e.,
       including \cs{newtoks}, and similars. When these are 
       part of the format or tool, multiple use 
       reallocates memory, and because \TeX{}
       lacks a garbage collector this will cost extra
       memory locations
\bitem sometimes a different macro name for \bluetex{} is needed, such as 
       the index tool.
\smallbreak
The \cs{tool} macro accepts any |<yourtoolname>|

\bluesubhead And what about double loading?

At the moment it is printed in the log file, whenever a tool is loaded.
Sometimes we wish to load a tool anew, for example the pascal
environment.
The index tool is only loaded once.\ftn{Very handy when after
    having proofed chapters with an index generated on the fly,
    we don't have to delete the \cs{loadindexmacros} tag in the chapters.}   
A load counter is maintained to control this. 

\bluesubhead Check for data integrity

After a tool has been added one can check whether the file can be scanned by
\TeX{} via making a table of contents as follows.
\begincenterverbatim
\input blue.tex
\contentstoolsorfmt{tools}
\bye
!endcenterverbatim
This script produces no pages of output (that is OK). 
The file contentstools will be created though.

\bluesubhead Verbatim listing of a tool

This problem is induced by my multi-file approach. Of course
one can extract the tool by an editor et cetera as alternative.

\blueexample Verbatim listing of macros of pascaltool 

\begincenterverbatim
\input blue.tex \let\pascaltool=x
\long\def\tool#1{\ifx#1\undefined\bgroup\unouterdefs\ea\gobbletool
   \else\ea\toolverbatim\fi}
%\def\toolverbatim{\thisverbatim{\baselineskip12pt plus2pt minus1pt
%   \lineskip1pt plus1pt minus1pt}\beginverbatim}
\def\cgl;newcol{\endverbatim\endinput}
\input tools.dat \bye
!endcenterverbatim

\thissubhead{\runintrue}
\bluesubhead Conventions for entries fmt.dat\par come down to 

\bitem update the contents at the beginning of the file tools.dat
\bitem |\message{ ---<...>tool, <date>, <owner>--- }| in the beginning
\bitem visual layout for  print out
\bitem additional comments which contain markup for line numbering
\bitem addition of table of contents with cross-ref line numbers
\bitem addition of history of changes.
\smallbreak
The layout is aimed at printing in two columns, and start  a new column.
The selective line numbering is controlled by the control sequences
\cs{numvrb}, to start line numbering
\cs{vrblin} = |<number>|, to adjust line counter, and
\cs{nonum} to switch off line numbering.
Do remember that the escape char is the semi-colon.

\blueexample Template for an entry in tools.dat

\begincenterverbatim
%end%%%%%%<lastlineprevioustool>%;newcol
%
%
%begin%%%%%%%%%%%%%%%%%%%%<....>%;numvrb
\tool\<...>tool
\message{ ---<...>tool, <date>, 
                      <(cr)owner>--- }
%<authorinformation>
%<thetoolproper>
\endinput                        %;nonum
%Contents
%<item>...................<pagenumber(s)>
%etc
%History of changes
%<date> <change>                 
%etc                             
%end%%%%%%%%%%%%%%%%%%%%%%%<....>%!!cgl;newcol
!endcenterverbatim

\bluehead Binary tree

^^|\beginbinarytree|^^|\beginbt|
The syntax of the invocation reads
\thisverbatim{\unmc}
\begincenterverbatim
\beginbintree<nodeno><nodevalue>
              ...
             <nodeno><nodevalue>
<levelno>\endbintree
!endcenterverbatim
See the Tabulair Material chapter for an example.
There is also an example about \cs{beginbt}\dots\cs{endbt},
a variant\Dash and smarter\Dash implementation of typesetting a binary tree. 
The specification of the nodes and their contents
contains less curly braces.\ftn{blue.tex also contains
   \cs{bintree} \cs{eertnib}, see the Pictures chapter for an example.}

\bluehead Bridge

^^|\beginbridge|%^^|\endbridge|
This is available within the environment
\displaycenterline{|\beginbridge...\endbridge|.}
the following has been copied from the \cs{bridgetool}.
\beginverbatim
%Typesetting bridge publications via (plain) TeX. Version May 92.
%The macros can als be used within LaTeX.
%Version: 1.1 March 1994 (basically unmodified since publication in 1990)
%Author: Kees van der Laan,Hunzeweg 57, 9893PB, Garnwerd (Gr)
%        The Netherlands. 05941-1525, cgl@rc.service.rug.nl
%Examples of use have been published in TUGboat, 11, 2, 265--276, and 
%MAPS 91.2. 
%The macros consist of 3 independent parts:
%- dec.tex   ((language) declarations, register used and control sequences)
%- bid.tex   (macros for bidding and layout of games)
%- play.tex  (macros for discussing the course of a play)
!endverbatim

\blueexample Bridge bidding, and play

The following has been copied from the \cs{bridgetool}. The `course of play'
has been printed in the chapter `Tabular Material.'
\beginverbatim
%Examples: diagram, bidding, course of play.
%1. Diagram
$$\crdima{N/None}{\vtop{\hbox{Deal:}\hbox{demo}}}%
  {\hand{J74}{AJ}{QJT2}{Q874}}%N
  {\hand{K86}{T9542}{874}{T3}}%E
  {\hand{QT952}{Q83}{AK5}{A6}}%S
  {\hand{A3}{K76}{963}{KJ952}}%W
$$
%2. Bidding
$$\bbid
1\cl\alert& ? no& 1\sp&\think no\cr
       2\sp&  no& 4\sp&     a.p.\cr
\noalign{\vskip.5ex}%With the explanation
\alert\ means Alert, conventional bid\hidewidth\cr
? means explanation asked            \hidewidth\cr
\think means think pause             \hidewidth\cr
\ebid $$
%3. Course of play
\def\LFTINF{Puzzle} \def\RGTINF{\vtop{\hbox{6NT,}\hbox{by East}}}
\Ns={KQ76}\Es={T9}\Ss={8542}\Ws={AJ3}
\Nh={J98} \Eh={A2}\Sh={QT74}\Wh={K653}
\Nd={J942}\Ed={T5}\Sd={Q876}\Wd={AK3}
\Nc={65}\Ec={KJ9xxxx}\Sc={2}\Wc={AQT}
%
\showgame
%
*Problem* How must NS defend in order to guarantee 1 trick?
*Solution* Start with a \h\ lead in order to break communication.
N must discard \h s and S must discard \sp s.
\smallskip\noindent
\LEADS\bplay
h4! & hK & h8 & h2 & --& 1\LEADW\cr
cA  & c5 & cx & c2 & --& 2\cr
cQ  & c6 & cx & s2 & --& 3\cr
cT  & h9 & cK & s4 & --& 4\LEADE\cr
cJ  & s5 & s3 & s6 & --& 5\cr
c9  & s8 & h5 & s7 & --& 6\cr
cx  & d6 & sJ & d2 & --& 7\cr
\bintermezzo
\def\RGTINF{\vtop{\hbox to 0pt{NS squeezed on\hss}
             \hbox to 0pt{\cl\ continuation?\hss}
             \hbox to 7ex{\hss}}} %phantom for alignment
\Ec={{\ooalign{\hfil\raise.07ex%
    \hbox{x}\hfil\crcr\mathhexbox20D}}}
\showgame  \Ec={x}
\eintermezzo
cx & h7 & h6 & hJ & --& 8\cr
\omit et cetera \hidewidth \cr
\eplay
!endverbatim

\bluehead Crosswords

^^|\begincrosswords|%^^|\endcrosswords|
This is available within the environment
\displaycenterline{|\begincrosswords...\endcrosswords|.}
For an example of use see the `Tabular Material' chapter.

\bluehead Tower of Hanoi

^^|\hanoi|
This is available as a command but acts as an environment. 
\displaycenterline{|\hanoi{...}|.}
An example is provided in the `Tabular Material' chapter.

\bluehead Creation of an Index

This is different. ^|\loadindexmacros| should be provided
at the beginning of the script.
At the end supply ^|\sortindex|, followed by ^|\pasteupindex|.
See the `Creation of an Index' chapter for more details.

\bluehead NTG logo

When ^|\loadntglogo| is invoked, the logo will be set in a vbox,
\cs{ntglogobox}, for multiple use via for example |\copy\ntglogobox|.

\blueexample Use NTG logo from tools.dat

\begindemo
\loadntglogo
\copy\ntglogobox
!yields
\loadntglogo
\copy\ntglogobox
\enddemo

\bluehead Pascal texts

^^|\beginpascal|%^^|\endpascal|
This is available within the environment
\displaycenterline{|\beginpascal...\endpascal|.}
An example has been provided in the `Text' chapter.

\bluehead Smileys

Just provide \cs{smiley}, \cs{winksmiley}, or \cs{sadsmiley} for 
\smiley
\winksmiley
\sadsmiley.

\bluehead xyz-axes

This is available as macro \cs{xyz} with three (text label) arguments.
The macro can be invoked after \cs{loadxyz}.
\endinput