\input blue \loadindexmacros \report \hfuzz=15pt \bluechapter Formats \beginsummary Next to the regular format BLUe's format contains the report and transparencies formats. The letter and concert format from the \TeX book have been reviewed and the goodies in there have been borrowed. The letter format makes use of the address.dat database. Treated are among other things how to use the formats, how to proof separate chapters of a report, how to create and update a set of transparencies, how to format letters, make address labels, and how to extend the databases by a format, tool, or address of your own. A table of main tags and a list of the Frequently Used Tags, for the letter, report and transparencies format, have been included. \endsummary Before delving into the details of the database approach, I'm happy to let you know that you can do without it, can fall back on the traditonal method of file inclusion, if for some reason or other you don't feel comfortable with databases. For example, if you like to make use of the transparencies macros from BLUe's format, copy the relevant part from fmt.dat into, say, trspar.tex. Then proceed as usual, for example as follows. \begincenterverbatim \input blue.tex \input trspar.tex !endcenterverbatim On the other hand those who like the database approach can peruse `BLUe's Format databases.' ^^{database,\ fmt.dat} \bluehead Use of formats from fmt.dat database To use a format just start a script with\ftn{Inclusion of files etc. is handled behind the scenes. Default the format is suited for an article.} \displaycenterline{|\input blue.tex \|} The markup tags are upwards compatible, i.e., the tags from the regular \bluetex{} are still there, but extended with extra tags. The coding of the tags from the default format have been adapted to the look-and-feel of |\|, the design if I may say so. \bluesubhead Adding a format To ^{add\ a\ format} to the BLUe's format system the following has to be done. \bitem separate the storage-allocating control sequences from the format, i.e., treat \cs{newtoks} and the like separately \bitem add the allocation control sequences to \bluetex \bitem add the format with an `opening' and `closing' to fmt.dat \bitem add a load macro to \bluetex. \smallbreak In actual fact this comes down to the following. Add to fmt.dat \begincenterverbatim \tool\fmt%Opening \endinput %Closing !endcenterverbatim and include in the kernel \bluetex{} the load macro and the storage allocations ^^{entry\ for\ fmt.dat} \thisverbatim{\catcode`\|=12 \catcode`\!=12 \catcode`\~=0 } \begincenterverbatim %load macro \def\{\let\fmt=x \loadformat \let\fmt=\undefined } %storage allocations \new\ % is one of box count dimen fam insert language skip % muskip read toks write %et cetera ~endcenterverbatim Note the difference between |\| and |\fmt|. Take care that |\fmt| remains undefined afterwards. Now and then I safeguarded formats from double loading. There are a few restrictions on the macros, as a consequence of the skipping mechanism used, via \TeX's argument processing. \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| \bitem no blank lines, insert \% \smallbreak Remarks. The restriction with respect to your outer defs can be circumvented by \bitem define all macros non-outer, or \bitem use |\csname newtoks\endcsname\|, and the like, or \bitem extend \cs{unouterdefs} by your outer defs, i.e., include \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. \smallbreak \bluesubsubhead Check for data integrity After a format 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{fmt} \bye !endcenterverbatim This script produces no pages of output (that is OK). The file contentsfmt will be created though. \bluesubsubhead Verbatim listing of a format This problem is induced by my multi-file approach. Of course one can extract the format by an editor et cetera as alternative. \blueexample Verbatim listing of letter format \begincenterverbatim \input blue.tex \let\letterfmt=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{\endverbatim\endinput} \input fmt.dat \bye !endcenterverbatim \bluesubsubhead Conventions for entries fmt.dat come down to \bitem update the contents at the beginning of the file fmt.dat \bitem supply |\message{ ---<...> format, , --- }| in the beginning \bitem take care of visual layout for print out \bitem provide additional comments which contain markup for line numbering \bitem add history of changes \bitem add a table of contents with line numbers. \smallbreak The layout is aimed at printing in two columns and starts in a new column. The selective line numbering is controlled by the following control sequences \item{}\cs{numvrb}, to start line numbering \item{}\cs{vrblin} = ||, to adjust line counter, and \item{}\cs{nonum} to switch off line numbering. \smallbreak Do remember that the escape char is the semi-colon. \blueexample Template for an entry in fmt.dat \begincenterverbatim %end%%%%%%;newcol % % %begin%%%%%%%%%%%%%%%%%%%%%<....>%;numvrb \tool\<...>fmt \message{ ---<...> format, , --- } % % \endinput %;nonum %Contents %................... %etc %History of changes % %etc %end%%%%%%%%%%%%%%%%%%%%%%%<....>%!!cgl;newcol !endcenterverbatim \bluehead Concert format Please open \TB{} on page {\oldstyle411}. What about this concert announcement? I never received such a leaflet when attending a concert. ^^{format,\ concert} The ones I got are prettier, so there is no use in copying this template.\ftn{I have included the macros in the format \cs{concert} nevertheless, for your convenience.} This is more or less in agreement with what Knuth states \beginquote\noindent \llap`Notice that the \cs{composition} and \cs{movements} and \cs{soloists} macros do not include any special provision for vertical spacing; the user is supposed to insert \cs{smallskip}, \cs{medskip}, and \cs{bigskip} as desired. This was done deliberately, because different concert programs seem to demand different spacing; no automatic scheme actually works very well in practice, since musical literature is so varied.' \endquote What can we learn from the format, especially the macros? Usually a lot. Here we go. \bitem The simple ^{size-switching macros} are nice, intelligible, and compact, because we don't deal with math in this context. The tags are just \cs{smalltype}, \cs{medtype}, and \cs{bigtype}. A pedagogical stepping stone for size-switching macros in general. \bitem The ^|\tsaologo| is nice too. I have used it for delineating parts in `Math into BLUes.' My variant is the macro ^|\partlogo| with the text as argument. The latter is part of \bluetex. \bitem The ^|\soloists| macro deserves more general use. It shows how to use \cs{halign} to {\sl center a block of text}. Moreover, it can be recast into a two-part macro. Note that \cs{centerline} has been used, but the \cs{vbox} could have been replaced by math display markup with the automatic insertion of \cs{displayskip} before and aft. And why not get rid of the \cs{cr}? Natural input? A matter of taste? I agree partly. The advantage is the extra option possibility after the opening keyword. In this case we can parameterize over the font to be used. \smallbreak \bluesubhead Centering a block The coding of \cs{soloists} can be combined with the coding of \cs{begindisplay}, \TB{} {\oldstyle421}, to yield a two-part macro for centering a block, with the flexibility to specify the font after \cs{begincenterblock}. Moreover, I incorporated the natural markup idea. No \cs{cr} has to be supplied by the user, \TeX{} will insert those. The macro is part of \bluetex. ^^|\begincenterblock|%^^|\endcenterblock| \begincenterverbatim \def\begincenterblock{\bgroup \let\par\cr\obeylines\startcenterblock} {\obeylines\gdef\startcenterblock#1 {$$#1\vbox\bgroup\halign\bgroup&##\hfil\cr}} \def\endcenterblock{\egroup\egroup$$\egroup} !endcenterverbatim \blueexample The soloists macro; block centering \begindemo \begincenterblock\bf Ben Lee User, horn Peter Schickele, hardart \endcenterblock !yields \begincenterblock\bf Ben Lee User, horn Peter Schickele, hardart \endcenterblock \enddemo Remark. The disadvantage of this macro is that no page break will occur within the vbox. % As usual there are advantages and disadvantages. \bluehead Letter format Please open \TB{} on page {\oldstyle403}, and you will see a marvel of natural markup. Only {\oldstyle5} tags are needed to mark up a letter. ^^{format,\ letter} \begincenterverbatim \letterhead \address \body \closing \endletter !endcenterverbatim If this is such a great approach, how come that it has not been taken over? IMHO, with all respect, it was too difficult to customize. At the time \TeX ies were busy porting the system to the various platforms. Moreover, nowadays I would like to \bitem store addressees in a database, and use them from there ^^{database,\ address.dat} \bitem have a simpler letterhead \bitem let ^|\headline| take care of the headers \bitem use fewer fonts, prevent suffering from fontitus \bitem use the known sender\Dash remember BLUe's format is yours, it knows about your context \bitem use window envelopes \bitem introduce token variables for ^|\subject|, ^|\yourreference|, and ^|\ourreference| \bitem make positioning of the address flexible in such a way that it can move to adjust to your window envelope \bitem adapt \cs{makelabel}\ftn{I named it \cs{makelabels}.} to work independenly with the address.dat database (Handy for address labels for carbon copies among other things) \bitem substitute \cs{beginscript} for \cs{beginletter} and ditto for the \cs{endscript}.\ftn{Well, \dots\thinspace I allowed \cs{beginletter} as alias, ditto for \cs{endletter}.} ^^|\makelabels|\smallbreak Because of the above, it is of no use to include the letter format literally from \TB. Furthermore, I simplified the approach a little, :-))), to facilitate customization. The variant has been incorporated as \cs{letter} format in the fmt.dat database. Note. The \cs{footline} on the first page is free to contain business information like giro, Chamber of Commerce number and the like. BLUe's format contains a toks variable \cs{businessaccount} for that purpose. See NTG's letter format. \bluesubhead Use of the letter format In order to use this format the user has to customize his letter format and make sure address.dat is available.\ftn{Well, the latter can be circumvented if \cs{loadreference} is replaced by a def with the name of the addressee, followed by the affiliation of which each line is preceded by |\\|, as replacement text.} ^^{script,\ letter} \begincenterverbatim \input blue.tex \letter %Knows about logo, sender \subject{...} \yourreference{...} \ourreference{...}%just numbers \addresses{\} %load list of address{es} \addressee{\} \beginscript \dear .... \sincerely %knows about you \cc ... %Optional set cc. .... \ps ... %Optional set P.S. .... \appendix{} \endscript !endcenterverbatim The \cs{appendix} control sequence takes one argument. It starts a new page but continues numbering. %The material will be set after an \cs{item}. If the letter proper is stored in letter.tex, then the use looks even simpler. \begincenterverbatim \input blue.tex \letter %Knows about logo, sender \subject{...} \yourreference{...} \ourreference{...}%just numbers \letterto{\...} !endcenterverbatim \blueexample A letter script; a letter to Don Knuth \beginverbatim \input blue.tex \letter %Preliminary initializations \subject{\TeX{} for BLU} \ourreference{22 1 95} \yourreference{\TB} \addresses{\knuthde} \addressee{\knuthde} %Initializes \addresseename \affiliationbox %\thisscript{\notlastscript} \beginscript %\beginletter is an alias \dear First of all I'm much obliged to your works especially \TB. As you know roughly 10k organized users profit from your system in getting their work out. It is estimated that the number of {\sl unorganized\/} users is a tenfold. I like your Ben Lee User character very much, and hope he will benefit from my work towards understanding and using \TeX{} with confidence. \bigskip What puzzles me is that manmac has been neglected so much. Is it because a user's guide was lacking? Was \TeX{} too far ahead of its time? Too unusual? \bigskip I'm also puzzled about the neglectance of the letter format. Was it too difficult for \TeX ies to customize at the time? I mean, it is confusing to mix the line mode and the par mode. As you can see from the \cs{letter} format I included, as part of BLUe's format, I refrained from those and concentrated on customization. I also made use of a database of addresses, but that is a minor \TeX nical point, because the markup abstracts from that detail as it should. Just |\adressee\|. \bigskip Whatever the reasons, I hope that my work will ease the use of manmac, or even better BLUe's format. The latter has manmac assimilated, and taken notice of experience gained since the release of manmac. \bigskip After this work on using \TeX{} I intend to write another booklet on \TeX{} macro writing, to emphasize two-part macros, because two-part macros are in the dark in the \TeX book. They are lacking in the chapter on macro writing, but have been used in manmac, and therefore are dealt with in Appendix~E. IHMO, with all respect, they deserve more attention. By that time, I hope to be familiar with `\TeX{} The Program' too. \bigskip In near future I'll direct myself to \MF, well META{\smc post}, and pay attention to {\oldstyle2}.{\oldstyle5}-D applications. I have in mind to emulate the works of Naum Gabo, a sculptor, whose objects I like very much. The exciting thing in there is that I can emulate the work in {\oldstyle2}.{\oldstyle5}-D with only {\oldstyle1}-D information. The latter is quite obvious because he used regular surfaces. However, it is apparently me who arrived at the crossroads. \bigskip I would appreciate it very much if you would let me know that you have received this work, and of course, I welcome suggestions. \sincerely \ps When I entered `Het Nederlands Rekenmachine Genootschap,' in {\oldstyle1967}, the first volume of the Art of Computer Programming was given to me, because of my lucky membership number, {\oldstyle1024}. I really could not foresee at the time that my interest in your work would take this turn \cc NTG \endscript !endverbatim \storedpageno\count0 \storedheadline\headline \storedfootline\footline \newpage {\letter %Preliminary initializations \subject{\TeX{} for BLU} \ourreference{22 1 95} \yourreference{\TB} \addresses{\knuthde} \addressee{\knuthde} %Initializes \addresseename \affiliationbox \thisscript{\notlastscript} \beginscript \dear First of all I'm much obliged to your works especially \TB. As you know roughly 10k organized users profit from your system in getting their work out. It is estimated that the number of {\sl unorganized\/} users is a tenfold. I like your Ben Lee User character very much, and hope he will benefit from my work towards understanding and using \TeX{} with confidence. \bigskip What puzzles me is that manmac has been neglected so much. Is it because a user's guide was lacking? Was \TeX{} too far ahead of its time? Too unusual? \bigskip I'm also puzzled about the neglectance of the letter format. Was it too difficult for \TeX ies to customize at the time? I mean, it is confusing to mix the line mode and the par mode. As you can see from the \cs{letter} format I included, as part of BLUe's format, I refrained from those and concentrated on customization. I also made use of a database of addresses, but that is a minor \TeX nical point, because the markup abstracts from that detail as it should. Just |\adressee\|. \bigskip Whatever the reasons, I hope that my work will ease the use of manmac, or even better BLUe's format. The latter has manmac assimilated, and taken notice of experience gained since the release of manmac. \bigbreak After this work on using \TeX{} I intend to write another booklet on \TeX{} macro writing, to emphasize two-part macros, because two-part macros are in the dark in the \TeX book. They are lacking in the chapter on macro writing, but have been used in manmac, and therefore are dealt with in Appendix~E. IHMO, with all respect, they deserve more attention. By that time, I hope to be familiar with `\TeX{} The Program' too. \bigskip In near future I'll direct myself to \MF, well META{\smc post}, and pay attention to {\oldstyle2}.{\oldstyle5}-D applications. I have in mind to emulate the works of Naum Gabo, a sculptor, whose objects I like very much. The exciting thing in there is that I can emulate the work in {\oldstyle2}.{\oldstyle5}-D with only {\oldstyle1}-D information. The latter is quite obvious because he used regular surfaces. However, it is apparently me who arrived at the crossroads. \bigskip I would appreciate it very much if you would let me know that you have received this work, and of course, I welcome suggestions. \sincerely \ps When I entered `Het Nederlands Rekenmachine Genootschap,' in {\oldstyle1967}, the first volume of the Art of Computer Programming was given to me, because of my lucky membership number, {\oldstyle1024}. I really could not foresee at the time that my interest in your work would take this turn \cc NTG \endscript \newpage} %Restore previous values \count0\storedpageno\advance\count0by3 \headline\storedheadline \footline\storedfootline \onecol%Restore \vsize \bluesubsubhead Syntax entries address database The address.dat database contains addresses sorted on name. Each entry obeys the syntax, as shown by the following example. ^^{entry\ for\ address.dat} \begincenterverbatim \lst\{ %Each line preceded by \\ \\ \\ \email{...}%optional \phone{...}%Optional } !endcenterverbatim \blueexample Entry address.dat database \begincenterverbatim \lst\ntg{NTG \\Nederlandstalige \TeX{} Gebruikersgroep \\Postbus 394 \\1740 AJ Schagen \\The Netherlands \email{ntg@nic.surfnet.nl} \registeredbluetrue } !endcenterverbatim To ^{add\ an\ address} just adhere to the syntax, and include the new address in address.dat, in the right order. Note that it is also possible to introduce fields, which can be used in a query and otherwise don't hinder, like \cs{registeredbluetrue}. ^^{field of database} \bluesubsubhead Check for data integrity After an address 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 \contentsdatabase{address} \bye !endcenterverbatim This script produces no pages of output (that is OK). The file contentsaddress will be created though. If you have a file with addresses of your own, say abc.dat, provide also \cs{newwrite} \cs{tocabc}. \bluesubsubhead Multiple letters Erik Frambach asked me how to format ^{multiple letters}, with each letter personalized by incorporating the address. If we are talking of a few letters there is no problem at all. Store the letter in a file and repeat the formatting for each letter. Let us assume that we wish to address a list of addressees, and that these addressees are already in our database address.dat. The approach to solve this is to go through the list of adressees, via FIFO, and `process' each with the letter. ^^{fifo} \begincenterverbatim \input blue.tex \letter \subject{\TeX{} for BLU} \yourreference{\TB} \ourreference{1$\,$2$\,$95} \letterto{\knuthde\ntg} \bye !endcenterverbatim This scheme also works for one letter. Note that after Dear the salutation name is used, which gives a personal flavour. \bluesubsubhead And what about a letter to the complete address database? Logically, this is simple. Make a list of all the names of the database elements and supply this list to ^|\letterto|. We can let \TeX{} do all the work, by using ^|\lettertoall| as follows. \begincenterverbatim \input blue.tex \letter \subject{\TeX{} for BLU} \yourreference{\TB} \ourreference{1 2 95} \lettertoall \bye !endcenterverbatim An interesting application is that for example NTG can send a\Dash more or less personalized\Dash letter to all its members. \bluesubsubhead Address labels Especially for the case of carbon copies separate address labels are wanted. For that purpose I modified Knuth's \cs{makelabel} into ^|\makelabels|. ^^|\makealllabels| \begincenterverbatim \input blue.tex \letter \makelabels{\knuthde\ntg} %and all address labels %can be obtained via \makealllabels \bye !endcenterverbatim If you prefer smaller address labels provide \cs{twocol}. \bluesubsubhead Searching the address.dat database by pattern ^^{search\ of\ database} BLUe's format provides a \cs{search} macro with a search pattern as argument. The purpose is to search the database file provided in the toks variable \cs{searchfile}, for this search pattern. The result of the search is a list of names, of which the replacement text contains the search pattern. This list of names is delivered in the toks var \cs{namelist}, and for the time being they are also written to the log file. \blueexample Search for addresses from RUSSIA in the database address.dat In order to justify my use of the word database in relation to \TeX, I provided the search macro to browse the databases lit.dat and address.dat. Below the input and result have been given of the search of address.dat for the pattern RUSSIA. The result is contained in the toks variable \cs{namelst}. The names are also written to the log file to give you a check for whether the right names have been selected. \begindemo \input blue.tex \searchfile{address} \search{RUSSIA} \bye !yields \cs{lst}\cs{gorbunovai} \cs{lst}\cs{grinevaoa} \cs{lst}\cs{makhovayai} \enddemo This is handy for making address labels grouped per country. \begincenterverbatim \input blue.tex \letter \search{RUSSIA} \makesearchlabels \bye !endcenterverbatim ^^|\makesearchlabels| ^^|\makesearchletters| \exercise Do you see the extension for sending letters to all those people? \answer BLUe's format system contains the command \cs{makesearchletters}, similar to \cs{makesearchlabels}. Remarks. A search pattern should not contain a period. The search is case sensitive. \bluesubsubhead Sorting the address.dat database ^^{sorting\ of\ database} With databases a convenient aspect while reporting is the possibility of sorting the database on secondary keys. Below I have included by example how this can be achieved.\ftn{In `Sorting in BLUe' I have shown how address labels can be sorted all within \TeX. At that time I had not yet incorporated the database idea within \TeX.} The idea is that the `list' of names of the database entries are sorted according to the criterion. Because blue.tex's sorting macros sort an array, the list is stored in an array. The major steps for typesetting the membership database sorted on (membership) number, are that the {\em names\/} of the database entries are \bitem stored in the array |\1, \2, ... , \| \bitem redefined with the value of \cs{no} as replacement text \bitem sorted \bitem redefined with the database entry as replacement text, and \bitem typeset. \smallbreak \blueexample Sorting address.dat on number The sorting of address.dat on (membership) number can be achieved with blue.tex as follows. \beginverbatim \loadindexmacros %Contains sorting macros \def\lst#1#2{%Function: \def\{#1} \def#1{}, with % \no{} last item in each database entry \advance\k1 \ea\def\csname\the\k\endcsname{#1}% \ea\def\ea#1\gobbletono#2} \def\gobbletono#1\no{} \k0 \input toy.dat %The test database \n\k %number of items No unsorted: \1, \2, \3, \4, \5, \6. %A snapshot \let\cmp\cmpn\sort Sorted on no value: \1, \2, \3, \4, \5, \6. \def\lst#1#2{\def#1{#2}}%Redefine names by their database entry \input toy.dat Database entries sorted on no value: %For typesetting we need \let\\\par \def\no{\\Number=} \def\phone{\\Phone: } \def\email{\\Email: } %Typeset entries with increasing membership number \smallskip\1\smallskip\2\smallskip\3\smallskip\4\smallskip\5\smallskip\6. \bye !endverbatim Each entry of the database is a triple \cs{lst}, |\|, and a group, with the group structured as shown in the syntax of an entry of the (toy) membership database given below. \beginverbatim \lst\{ \\ \\
\email{
} \phone{} \no{} } !endverbatim \bluesubhead Customization If there is one format which is candidate for customization this is the one. However, much information is already known by the system, like \cs{author}, \cs{address}, \cs{logo}, et cetera. Also addressees are known because of the address database. What is left is to position the address in the address window. BLUe's format provides the skip variables \cs{haoffset} and \cs{vaoffset}. These determine the shifts of the address within the window, horizontally or vertically, respectively. When you are not satisfied with the basic layout then the \cs{headline} and \cs{footline} have to be rewritten, because how the information is pasted up will be taken form these token variables. How to design your own letter format is beyond the scope of this user's guide. \bluesubsubhead And what about a letter on behalf? Suppose your letter has to be sent by fax and signed by a formal organization instead of yourself. How can we achieve this? A real-life example is a letter I sent to the ISF signed by the secretary of the NTG. The key to the solution is to know which variables to adjust. It is not that difficult to look for those in the fmt.dat file in the letter part. ^^{letter on behalf} Tht letter format comprises a {\oldstyle100} lines or so. Here they are anyway: \cs{address}, \cs{netaddress}, \cs{businessaccount}, \cs{fullname} and \cs{affiliationbox}. (In general redefine also \cs{ntglogobox}.) The greetings is inserted explicitly. \beginverbatim \input blue.tex \letter %\fax{(202)342-2765} \subject{Request J. Soros travel grant} \ourreference{5} \yourreference{} %\addresses\isf\addressee\isf %Switched off, details exlicitly provided %To override defaults from BLUe.tex %address sender \address{Postbus {\oldstyle394}\\{\oldstyle1740}AJ Schagen\\The Netherlands} \netaddress{ntg@nic.surfnet.nl} \businessaccount{\vtop{\hbox{\strut KvK Groningen nr V{\oldstyle025936}} \hbox{\strut GIRO {\oldstyle1306238}, NTG}}} %addressee \setbox\affiliationbox\hbox{International Science Foundation\\ Washington\\USA} \fullname{ISF} %Used in headline follow pages \beginscript %\beginletter is an alias L.S., \bigskip The NTG ---Dutch language-oriented \TeX{} Users Group--- is organizing the Euro\TeX{} {\oldstyle95} meeting, September {\oldstyle4}--{\oldstyle8}, at Arnhem. \bigskip Our plan is to facilitate participation from East and Mid European countries, i.e., from CSTUG, CyrTUG, GUST, and HunTUG, not on an individual basis but for some 50 members in total of those groups. \bigskip We are convinced that this project will stimulate scientific cooperation between East and West and hope that the ISF will also support this effort by a grant. \begingroup%local re-assignation \author{G.J.H. van Nes\smallskip {\small secretary NTG}} \sincerely \endgroup \ps \TeX{} is the revolutionary computer-assisted typesetting system designed by D.E. Knuth. \cc CSTUG: Matematick\'y \'ustav UK, Sokolovsk\'a 83, CS-186 00 Prague, CZECH Republic\\(The Czech \TeX{} Users Group. horakk@earn.cvut.cz)\\ CyrTUG: MIR publishers, 2 Pervy Rizhsky pereulok, Moscow 129820, RUSSIA\\ (The Cyrillic \TeX{} Users Group from CIS{}. cyrtug@mir.msk.su)\\ GUST: Institut Bada\'n Systemowych PAN, ul.~Newelska 6, 01-447, Warszawa, POLAND\\(The Polish \TeX{} Users Group. tomasz@panda.bg.univ.gda.pl)\\ HunTUG: Institute of Mathematics and Informatics, Lajos Kossuth University of Debrecen, H-4010 Debrecen, P.O.B. 12, HUNGARY\\ (The Hungary \TeX{} Users Group. ludens@tigris.klte.hu)\\ \endscript !endverbatim Remark. Maybe I should make it possible to allow for multiple users, read senders of letters. \bluesubsubhead And what about enclosures? I was so preoccupied by letters completely processed by \TeX{} or its ilks, that I simply overlooked the wish to specify ^{enclosures} and include these fysically. Well, \dots no problem. Just define \beginverbatim \def\enclosures{\bigskip Enclosures: \small } !endverbatim and use this for example at the end\Dash just before \cs{endscript}\Dash as follows \beginverbatim \enclosures{Copy of bank payment} !endverbatim Creeping featurism? Let us put it positively: no unnecessary issues have been implemented, and when something is needed we can easily add it. \bluesubsubhead Your summary of main markup tags for letters The Frequently Used Tags, FUTs for short\Dash indeed a handful, as already indicated in the template in the `Introduction'\Dash for personalizing. Use it as crib. \beginverbatim !bf Letter proper!tt \addresses{...} \addressee{...} \subject{...} \yourreference{...} \ourreference{...}%only digits \letterto{...} \lettertoall \vaoffset \haoffset !bf Copy Proper!tt \beginscript \endscript \dear \sincerely \cc \ps \appendix{...} !bf Address labels!tt \makelabels{...} \makealllabels \makesearchlabels !endverbatim \newpage \bluehead Report format A report is set in one-column, with per page a header and footer. The header is suppressed for the preliminary pages and for every first page of a chapter. ^^{format,\ report} The latter starts with a title and summary followed by the copy proper. The footer is suppressed for the preliminary pages, i.e., these pages lack numbering, among other things. ^^|\chapterhead|^^|\summary| ^^|\begindemo|%^^|\enddemo| ^^|\yields| ^^|\displaycenterline| ^^|\begincenterdisplay|%^^|\endcenterdisplay| Some new control sequences are \begincenterdisplay \cs{preface} &for a preface\cr \cs{chapterhead} &for chapter title\cr \cs{setupappendices} &for letters as numbers\cr \cs{pasteup...} &to paste up elements\cr \endcenterdisplay Next to the coding of the new control sequences several existing control sequences had to be recoded to comply with \cs{report}. The reimplementation of ^|\beginscript| was tedious work, because it takes care of the preliminary pages: the cover page, the inside cover page, the title page, the preface page, and the table of contents page. |\endscript| takes care of the back cover pages. The implementation of \cs{(chapter)head} was tough work because of the wish to process on the fly and to store the title. On second thoughts I realized the more modest wish to allow for math in the titles, especially to handle the circumflex appropriately. Next to the a priori and physical table of contents in the front matter of the report, a table of contents with page numbers attached dynamically, is generated on the fly and appended at the end of the typeset report. The latter supports `drafting,' much in the spirit of developing a program supported by literate programming tools. A ToC, a ToE, or the set of answers, are generated on the fly and can be called up via \cs{pasteuptoc}, \cs{pasteuptoe}, respectively \cs{pasteupanswers}. The contents file can be edited and used for the static table of contents, finally. \bluesubhead Template The file for this report has all chapters included. However, while writing and proofing all chapters were kept in separate files. The latter structure, stripped from redundancies, has been included below as a template. ^^{script,\ report} If the preliminary matter is a little overwhelming, skip this section, and continue with `Proofing a single chapter.' \blueexample A report script; the outer markup for this report The template reads as follows. \thisverbatim{\catcode`\!=12 \catcode`\~=0 } \beginverbatim \input blue.tex %\loadindexmacros %When creating an index too \report %Cover data \bluetitle Publishing with \TeX \bluesubtitle BLUe's Selection \bluepictures \bluemodelpic %Inside cover data \bluekeywords Bibliography, \bluetex, ... \bibliographydata{ISBN: \dots\par ...} \beginacknowledgements First of all \displaycenterline{Don Knuth, Thank You!} ... \rightline{I'm grateful to all of you.} \endacknowledgements %Title page data (next to title&author) \beginabstract The use of \bluetex{} has been documented in a user's guide, ... \endabstract %Preface page data \beginpreface \vskip2\bigskipamount Dear User, \bigskip It occurred to me that my detailed studies ... will be beneficial for new-and-old \AllTeX ies alike. \bigskip \rightline{\the\author} \endpreface %Contents Page data %Because of \valign use, \contents{...} %is not possible. \begincontents %\se is subentry descriptive tag Preface Table of contents Introduction \se BLUe's format ... \se J: Table of Contents \endcontents \let\coverpic=\bluemodelpic %BLUe script proper \beginscript \input pwt.int %Introduction \input pwt.txt %Text %\endscript %For testing, to make script smaller \input pwt.mat %Mathematics \input pwt.tab %Tabular material \input pwt.grf %Pictures \input pwt.ref %References \input pwt.ind %Index creation \input pwt.cus %Customization \input pwt.aft %Afterthoughts % \setupappendices %From now on A, B, C,... \pasteupanswers %A: Answer to Exercises \input pwt.fmt %B: Formats \input pwt.tls %C: Tools \input pwt.sur %D: Backgrounds \pasteuptoe %E: Table of Examples \input pwt.tot %F: Table of tags \input pwt.his %G: History of changes \input pwt.obs %H: Obselete macros %\sortindex\pasteupindex %I: Index \pasteuptoc %J: Table of Contents \endscript ~endverbatim \bluesubhead Proofing a single chapter Chapters can be proofed separately as follows.^^{proofing single chapter} \beginverbatim \input blue.tex %\loadindexmacros \report %After \loadindexmacros \input %\sortindex\pasteupindex \bye !endverbatim Perhaps the easiest way to get results is to forget about the preliminary matter to start with. The above script formats your chapter and why not begin with |\chapterhead{...}| right away, instead of |\input |? We can easily test a few chapters in a row as follows. Omit \cs{bye} and when \TeX{} prompts for an \cs{end} insert `i' for insert and after the insert prompt supply \cs{input} ||. \bluesubhead Main tags for report format A table of main tags for \cs{report} has been included ^^{report format, main tags} to provide a survey of what outer tags\Dash and to what extent\Dash they have been implemented for the \cs{report} format.\ftn{More control sequences and symbols are available, especially for the lower level markup, if not for the undocumented features of manmac, and the wealth of plain \TeX.} The table also illustrates the naming convention of a root name with affixes. The header fields indicate, the prefixes pre-, post-, this-, every-, pasteup-, and the suffixes -font, -name and -box. The first column contains the various root names, with a marker to denote to what extent the minimal one-part macro has been implemented. \begingroup \def\first{\hfil\thispicture{\unitlength=6ex \xdim{1.4}\ydim{1}}% \lower1.5ex\hbox\beginpicture%(1.4, 1)(0,-.1) \put( 0.0, 0.0){\small \strut Root}% \put( 1.4, 0.575){\llap{\small Affix}}% \put( 1.4, 0.1){\line(-2, 1){1.4}}% \endpicture\lower3ex\null} \def\header{pre-\cs post-\cs this-\cs every- \cs pasteup- \cs -font\cs -name \cs -box} \def\btablecaption{Main tags for report scripts} \catcode`/=13 \def/{\leavevmode\thinspace\hbox{% \vrule\vtop{\vbox{\hrule\kern1pt\hbox{% \vphantom{\tt e}\thinspace%{\tt#1}% \thinspace}}\kern1pt\hrule}\vrule}% \thinspace} % control sequence token \catcode`-13 \def-{$\neg$} \def\footer{\qquad\vtop{\small\rlap{- not implemented} \rlap{${}^+$ implemented} \rlap{/ implemented without processing on the fly}}} \def\rowstblst{ {abstract\hfill\ \tiny+} {acknowledgements\hfill\ \tiny+} {btable \hfill\ \tiny/} {center \hfill\ \tiny+} {chapterhead \hfill\ \tiny+} {contents\hfill\ \tiny+} {(sub(sub))head\hfill\ \tiny+} {keywords\hfill\ \tiny+} {picture \hfill\ \tiny-} {pictures\hfill\ \tiny/} {preface \hfill\ \tiny+} {quote \hfill\ \tiny+} {references\hfill\ \tiny/} {script \hfill\ \tiny+} %{syntax\hfill\ \tiny-} %Although there, not so relevant for the table {summary \hfill\ \tiny+} {verbatim\hfill\ \tiny-}} \def\data{% -\cs-\cs-\cs-\cs+\cs-\cs+\cs+\rs%abstract +\cs+\cs+\cs-\cs+\cs-\cs+\cs+\rs%abstract +\cs+\cs+\cs+\cs-\cs-\cs-\cs+\rs%btable -\cs-\cs-\cs-\cs-\cs-\cs-\cs-\rs%center +\cs+\cs+\cs+\cs-\cs+\cs-\cs-\rs%chapterhead -\cs-\cs-\cs-\cs+\cs-\cs+\cs+\rs%contents +\cs+\cs-\cs-\cs-\cs+\cs-\cs-\rs%head -\cs-\cs-\cs-\cs+\cs-\cs+\cs+\rs%keywords -\cs-\cs+\cs+\cs-\cs-\cs-\cs-\rs%picture -\cs-\cs-\cs-\cs-\cs-\cs-\cs-\rs%pictures +\cs+\cs-\cs-\cs-\cs+\cs-\cs-\rs%preface -\cs-\cs-\cs-\cs-\cs-\cs-\cs-\rs%quote +\cs+\cs+\cs+\cs+\cs-\cs+\cs+\rs%references +\cs+\cs-\cs-\cs-\cs+\cs-\cs-\rs%summary -\cs-\cs+\cs+\cs-\cs-\cs-\cs-\rs%script % -\cs-\cs-\cs-\cs-\cs-\cs-\cs-\rs%syntax +\cs+\cs+\cs+\cs-\cs-\cs-\cs-%\rs%verbatim } $$\vbox{\nonruled\nonframed \btable\data}$$ \endgroup Remarks. \bitem ^|\title|, ^|\subtitle|, ^|\author| and the like, are token variables and associated with the script \bitem ^|\pictures| and ^|\references| have been implemented in a straightforward way, because their use doesn't need processing on the fly. \smallbreak \bluesubsubhead Your summary of main markup tags for reports The Frequently Used Tags, FUTs\Dash indeed a handful, as already indicated in the template in the `Introduction'\Dash for personalizing. \beginverbatim !bf Preliminary matter!tt \title{...} \subtitle{...} \keywords{...} \abstract{...} \contents{...} \issue{...} \acknowledgements{...} \references{...} \pictures{...} !bf Copy Proper!tt \beginscript \endscript \chapterhead{...} \summary{...} \head{ ...} \thissubhead{...} \subhead{...} \thissubsubhead{...} (the \this{...} especially together with \runintrue) \subsubhead{...} !bf Inner level!tt \begindemo...yields...\enddemo \thisverbatim{...} \beginverbatim endverbatim (and in-line !vrt!thinspace...!thinspace!vrt) \beginquote \endquote \begindisplay \enddisplay (with & and \cr) \displaycenterline{...} \begincenterdisplay \endcenterdisplay (with & and \cr) \btable (with \data{...\cs...\rs...\cs...\rs...} \header{...} \footer{...} \rowstblst{...} \vruled{...} ) \ref\ \crsref\ \ftn{...} \item{...} \itemitem{...} \aitem \Aitem \bitem \nitem \example{...} \thispicture{...} (with \unitlength=...) \cs{} !bf Back matter!tt \setupappendices \pasteupanswers \pasteuptoe \pasteupreferences \sortindex\pasteupindex \pasteuptoc !endverbatim \bluesubhead Addition of a format to BLUe's format system \blueexample Addition of report format to the fmt.dat database The following has been added to fmt.dat. ^^{add\ a\ format} \begincenterverbatim \tool\reportfmt \endinput !endcenterverbatim \bluetex{} has been extended with \thisverbatim{\catcode`\|=12 \catcode`\!=12 \catcode`\~=0 } \begincenterverbatim \def\report{\ifx\undefined\reportfmt\let\reportfmt=x\fi \ifnum\reportloadcnt=0 \ea\loadformat\fi \advance\reportloadcnt1 \let\reportfmt=\undefined} %Storage allocations for \report come next \newtoks\prefacename %et cetera ~endcenterverbatim \newpage \bluehead Transparencies format BLUe's format transparencies have a centered flavour, with a header part which reflects the series, and the context. ^^{format,\ transparencies} There is also room for a user logo to be printed in the header. Very error-prone is the line-by-line nature of a transparencies script. Beware! For example when providing a macro one should remember that each line end is special. Perhaps I should provide also \cs{disobeylines} to undo the \cs{obeylines}. \bluesubhead Template I like to start from an example, a template, which shows what has to be provided. ^^{script,\ transparencies} \blueexample Transparencies script \thisverbatim{\catcode`\|=12 } \beginverbatim \input blue.tex \pictures\bluemodelpic \transparencies \vfuzz=15pt \everyverbatim{\emc} \hsize14cm \leftskiptrs.2\hsize \rightskiptrs.1\hszie \title{BLUe's Format} \subtitle{the best of both worlds} \contents{WAF? Outer vs Inner markup Template Customization Coding Transparencies Tags survey Conclusions } \beginscript \head{WAF? } %Starts a new transparency, implicitly $$\thispicture{\xoffset{-1}}\bluemodelpic$$ \head{Markup language} %Starts a new transparency, implicitly \bitem |\begin...\end| |\| \hfill defs \bitem |\this| |\every| \hfill token vars \bitem \cs{title} \dots \hfill token vars \bitem |\pre| |\post| \hfill token vars \bitem |\pasteup| \hfill defs \smallskip \vfill \loadxyz$$\xyz{Alias tags}{Options}{Place within context}$$ \endscript !endverbatim The following pages contain the results. \cs{transparencies} has been used locally, and because of the nested use I inserted |\thisscript{\notlastscript}|. Note that \cs{pictures} has to be supplied before \cs{transparencies} because the latter turns \cs{obeylines} on. \newpage \subheadtitle{} \subsubheadtitle{} \storedpageno\count0 {\pictures\bluemodelpic \transparencies \hsize14cm \leftskiptrs.2\hsize\relax \rightskiptrs.1\hsize\relax \hfuzz30pt \vfuzz=15pt \everyverbatim{\emc} \title{BLUe's Format} \subtitle{the best of both worlds} \begincontents WAF? Outer vs Inner markup Template Customization Coding Transparencies Tags survey Conclusions \endcontents \thisscript{\notlastscript} \beginscript \head{WAF? } $$\thispicture{\xoffset{-1}}\bluemodelpic$$ \head{Markup language} \bitem |\begin...\end \| \hfill defs \bitem |\this| |\every| \hfill token vars \bitem \cs{title} \hfill token vars \bitem |\pre| |\post| \hfill token vars \bitem |\pasteup| \hfill defs \smallskip \vfill \loadxyz $$\vbox{\xyz{Alias tags}{Options}{Place within context}}$$ \endscript \nxttrs }%end transparencies intermezzo \count0\storedpageno\advance\count0 by3 \bluesubhead Use your logo ^|\logo| is a def, and invoked within \cs{line}. In order to have your logo, supply \begincenterverbatim \def\logo{\vbox to0pt{\vss ... %Your logo }} !endcenterverbatim \bluesubhead Maintenance This section is in a certain sense artificial, ^^{maintenance transparencies} introduced by the automatisms which come with my choices for the `header' and `footer,' especially the context-dependent information in there. The following might be helpful for modifying or extending single transparencies. The idea is to follow the script setup and handle the \cs{header}, \cs{pagenumber} and \cs{identification} for the particular transparency. In the example below the task was to add a transparency in between.\ftn{Without automatically gathering of context information the modifications are a trifle.} \begincenterverbatim \title{Literate Programming} \beginscript \head{Tools} \nxttrs \identification{feb94} \pagenumber{13a} \subhead{FWEB} LP tool by John Krommes \endscript !endcenterverbatim \bluesubhead Main tags for transparencies A table of main tags has been included ^^{transparencies format, main tags} to provide a survey of what outer tags\Dash and to what extent\Dash they have been implemented for the \cs{ transparencies} format. The table also illustrates the naming convention adopted via a root name with prefixes and suffixes. The header fields indicate, the prefixes pre-, post-, this-, every-, pasteup-, and the suffixes -font, -name and -box. The first column contains the various root names, with a marker to denote to what extent the minimal one-part macro has been implemented. \begingroup \def\first{\hfil\thispicture{\unitlength=6ex \xdim{1.4}\ydim{1}}% \lower1.5ex\hbox\beginpicture%(1.4, 1)(0,-.1) \put( 0.0, 0.0){\small \strut Root}% \put( 1.4, 0.575){\llap{\small Affix}}% \put( 1.4, 0.1){\line(-2, 1){1.4}}% \endpicture\lower3ex\null} \def\header{pre-\cs post-\cs this-\cs every- \cs pasteup- \cs -font\cs -name%\cs -title \cs -box} \def\btablecaption{Main tags for transparencies scripts} \catcode`/=13 \def/{\leavevmode\thinspace\hbox{% \vrule\vtop{\vbox{\hrule\kern1pt\hbox{% \vphantom{\tt e}\thinspace%{\tt#1}% \thinspace}}\kern1pt\hrule}\vrule}% \thinspace} % control sequence token \catcode`-13 \def-{$\neg$} \def\footer{\qquad\vtop{\small\rlap{- not implemented} \rlap{${}^+$ implemented} \rlap{/ implemented without processing on the fly}}} \def\rowstblst{ {btable \hfill\ \tiny/} {center \hfill\ \tiny+} {contents\hfill\ \tiny+} {(sub(sub))head \hfill\ \tiny+} {picture \hfill\ \tiny-} {pictures\hfill\ \tiny/} {quote \hfill\ \tiny+} {script \hfill\ \tiny+} %{syntax\hfill\ \tiny-} %Although there, not so relevant for the table {verbatim\hfill\ \tiny-}} \def\data{% +\cs+\cs+\cs+\cs-\cs-\cs-\cs+\rs%btable -\cs-\cs-\cs-\cs-\cs-\cs-\cs-\rs%center -\cs-\cs-\cs-\cs+\cs-\cs+\cs+\rs%contents +\cs+\cs-\cs-\cs-\cs+\cs-\cs-\rs%head -\cs-\cs+\cs+\cs-\cs-\cs-\cs-\rs%picture -\cs-\cs-\cs-\cs-\cs-\cs-\cs-\rs%pictures -\cs-\cs-\cs-\cs-\cs-\cs-\cs-\rs%quote -\cs-\cs+\cs+\cs-\cs-\cs-\cs-\rs%script % -\cs-\cs-\cs-\cs-\cs-\cs-\cs-\rs%syntax +\cs+\cs+\cs+\cs-\cs-\cs-\cs-%\rs%verbatim } $$\vbox{\nonruled\nonframed \btable\data}$$ \endgroup Remarks. \bitem ^|\title|, ^|\subtitle|, ^|\author| and the like, are token variables and associated with the script \bitem ^|\pictures| has been implemented in a straightforward way, because it doesn't need processing on the fly. \smallbreak \newpage \bluesubsubhead Your summary of markup tags for transparencies \beginverbatim !bf Token vars!tt \address\author\crowner%Default, already personalized \every... %See default blue.tex \footline \headline \headtitle \identification \pagenumber \posthead \postsubhead \postsubsubhead \prehead \presubhead \presubsubhead \subheadtitle \subsubheadtitle \subtitle \this...%See blue.tex \title !bf Control sequences with root name!tt center %default contents head pictures script !bf Auxiliaries!tt \continue \nxttrs !bf Lower level!tt \bitem \beginverbatim endverbatim !endverbatim For inner markup the macros from plain and those from \bluetex{} can be used. Load what you need before \cs{transparencies} because the latter turns \cs{obeylines} on. \displaycenterline{Do remember the line-by-line character of the script} \endinput