\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