path: root/info/laan/pwt/pwt.scr

%Copyright: C.G. van der Laan, cgl@rc.service.rug.nl, 31 59462 1525
%Started 22 November, 1994  %Version September 1995
\input blue.tex           
%Conventions
%-Titles of other work (also references by name to chapters) within single quotes
%Spelling
%-alphabetically or lexicographically
%-appendices, contrast with  prefixes, suffixes, affixes
%-ascertain
%-BLUe's format, BLUe script, blue.tex
%-cross-referencing
%-controlled (l always doubles)
%-developed
%-flavour, favour
%-file name, not filename, similar type name
%-govern
%-macro writing
%-mark up (verb), the markup (noun) 
%-occasionally
%-one pass and one-pass job (similar two-part macro; in line in-line text
%                            on line on-line documentation)
%-open-ended, open-endedness
%-page number, page size
%-parenthesize
%-rhombus-framed, similar pseudo-code
%-setup (similar to markup (noun))
%-shortcut
%-size-switching macros (not size switching)
%-user's guide (not user guide, nor users' guide)
%-user-friendly
%-uppercase letters (similar lowercase), upperright corner
%-word processor

\loadsmileys%Not necessary per se, but now these are globally available
\loadindexmacros
\report  %Format to be selected from the fmt.dat database 

\bluetitle Publishing with \TeX    %Cover data   
                                   
\bluesubtitle BLUe's Selection

\bluepictures \bluemodelpic

\def\coverpic{\qquad\qquad\bluemodelpic}             
%\translator{Irina Gorbunova}            

                                   %Inside cover data
\bluekeywords Bibliography, \bluetex{}, 
   citations, compatible extension, cross-referencing, customization, 
   databases, data integrity, education, fractals, 
   index, letter, manmac, mark up, math, minmal markup, pictures, no-nonsense,
   plain \TeX, programs, publishing,
   report, reuseable software parts,
   software engineering, supprematism, 
   tables, table of contents, table of examples, transparencies, trees, turtle graphics,
   verbatim.

%endkeywords

\bibliographydata{ISBN: \dots\par
                  Classification: \dots\par
                  Date: September {\oldstyle1995}
}%end bibliography data

\beginacknowledgements
First of all 
                 $$\hbox{Don Knuth, Thank You!}$$ 
for what you gave to the world, and to me in particular. 
I enjoyed so much studying your \TeX{} works.
I never perused a book so many times as \TB.

I owe many thanks to numerous anonymous people 
who contributed to my \AllTeX{} knowledge. 
I'm very grateful to NTG for bringing out early notes in MAPS, 
and to Erik Frambach and Wietse Dol for disseminating 
BLUe's Format system on the 4All\TeX{} CD-ROM.
With pleasure I look back at Bacho\TeX{} {\oldstyle 94}, where among 
others  Bogus\l aw Jackowski stimulated me to work on a manmac user's guide.
This emerged in BLUe's Format system and fitted well with my ideas about
a `Publishing with you-name-it' series.

The macros and styles of the \TUG, and the \AMS{} have been very inspiring. 
Of the former I borrowed the abbreviations and the approach of the OTR. 
The latter inspired me how to format references.
I'm not aware to what extent the excellent user and installation guides of
the AMS have influenced me. I like those for sure.
Amy Hendrickson made me familiar with two-part macros.
Amy's \cs{diagline} macro is part of \bluetex, although 
it is not much used by other macros, because of \LaTeX's line fonts. 
David Salomon's courseware has been a wealthy source, especially for 
macro writing.
Phil Taylor familiarized me with sequences of \cs{expandafter}s.
His \cs{ignorewhitespace} has been incorporated in \bluetex.
Bernd Raichle mentioned en-passant how to look at triples of \cs{noexpand}s.
Joseph Romanovsky stressed the importance of memory management, which resulted
in the general database approach.
Frans Goddijn made me appreciate the frisky \cs{oldstyle} numbers.
My perception of compuscripts has its roots in the SGML world. 
And, of course, I learned a lot from \LaTeX.  

Frank Poppe, Eric Veldhuyzen, and Jos Winnink, thank you 
for proofreading and for the useful comments.
Peter Frambach polished my use of English.\ftn{Any abuses left have to do
   with later versions he did not see.}
Erik Frambach, again, was of great help in the proofing phase. 
Many a suggestion with respect to the layout was prompted by him.
Irina Gorbunova%\the\translator
, my host when attending CyrTUG {\oldstyle93}, {\oldstyle94}, 
translated the script into Russian. 

Last but not least thank you Ina Kooi for your friendship, support
and patience.
\medskip
\rightline{\vbox{\noindent\hsize.4\hsize I'm grateful to all of you.}}
\endacknowledgements

                                      %Title page data (next to title&author) 
\beginabstract                        
The use of BLUe's format has been documented in a user's guide, 
to be released electronically in English and in Russian.
\par
The functionalities provided are similar to those of \LaTeX, to mark up
a note, an article, a set of transparencies, a report, and a letter.
The attitude is much different though. An example of the
latter is  processing of a modest index in one pass,
completely within \TeX, on-the-fly. 
\par
The concept of two clusters of markup tags is introduced, 
called the outer level markup tags and the inner level markup tags.
The former are responsible for the look-and-feel, 
and are kept to a minimum to cope with the inevitable change.
The latter constitute the lower level issues, and are aimed at stability,
invariance of representation and implementation, much in the spirit of
the frozen kernel of \TeX.
\par
Many examples, exercises and answers have been included.
\par 
The basic attitude has been to make \TeX{}
simpler to use, to let it look less confusing. 
To select from  the multitude of commands a handful, and to
elucidate what we need most of the time. 
\par
New  details treated are: 
the script concept,
the separation of outer and inner level markup,
using databases\Dash 
   formats, tools, references, pictures, and addresses\Dash 
in a one-pass job with \TeX,
macros to format Pascal programs,
a verbatim suite of macros to cooperate with Any\TeX,
selective line-numbering of verbatims,
a compatible extension of math cross-referencing,
some matrix icons,
a compatible extension of \cs{equalign} with multi-alignment points,
a simple approach to formatting of partitioned matrices,
a refined bordered table macro with the awareness of logical
rows and columns and attributes to control layout,
various codings of deterministic tables,
a new look at manmac's \cs{samplebox},
creation of a modest index in one pass,
design of a report format on top of \bluetex, and 
last but not least
a uniform coding approach to start from two-part macros and 
to build one-part macros on top of those,  parameterized
by |\this<tag>|, |\every<tag>|,  |\pre<tag>|, |\post<tag>|, and 
occasionally |\<tag>name|. 

I have built upon manmac and gkppic, and developed most of the macros myself. 
Ideas have been borrowed from the styles of TUG, AMS, from the
proceedings of the Euro\TeX{} and TUG meetings,
and from the articles in the bulletins of the various user groups.
Of course, many an idea came to mind when talking to friends at the various
\TeX{} User Group meetings.
The markup of  examples  released earlier has been improved,  simplified, 
or made more consistent.
\endabstract
                                   %Foreword translator data
\beginforewordtranslator

This guide is about BLUe's Format, aimed at
formatting documents in English via plain \TeX.
\medskip
What do we mean by a translation?
\medskip
For the time being it is just a translation of the
English into Russian, {\sl not\/} a transliteration
of the contents.
The latter entails that an index in Russian
is {\sl not\/} generated on the fly.
Another consequence is that this guide
is {\sl not\/} about the use of Cyr\TeX.
\medskip
Hopefully, the future will give birth to a real 
Russian BLUe's Format project.
\endforewordtranslator
                                    %Preface page data
\beginpreface
\vskip2\bigskipamount
Dear User,
\bigskip 
It occurred to me that my detailed studies 
as published in NTG's MAPS, such as
the BLUes series\Dash Manmac, TUGboat, AMS\Dash 
did not attract the attention it deserved, \winksmiley, 
let alone that people read it. 
They simply lack the time.
Similarly, the BLUe's series enjoys a modest audience. 
Most \TeX ies are just busy using \LaTeX.
Therefore, `Publishing with \TeX,' PWT for short, is not so much about
reading, but has all to do with using. 

My experience in macro writing comes from 
perusing Knuth's books,
attending Amy's and David's advanced \TeX{} classes,
looking into the works of colleagues, 
and inevitably experimenting.
The fundamental macro writing \TeX niques I have assimilated
will be reported in NTG's MAPS, in
backside of the envelope contributions, 
in what I call the Paradigm series. 

BLUe's format, its extensions and this user guide
`Publishing with \TeX,' are shareware available,\ftn{I would welcome 
   \$\thinspace{\oldstyle25} from each happy user, 
   to facilitate investment in hardware to maintain the format. 
   The PWT booklet alone is worth it \smiley.
   Of course, you will be added to my address database with filed
   \cs{registeredbluetrue}. Do provide
   complete affiliation, email included. Users in Russia can just send me
   a nice mail with their affiliation for the time being.}
and will be distributed electronically
on diskette, via NTG's CD-ROM, or 
can be  plucked from the CTAN. 
The relation between the various BLUe's articles and PWT is that the latter
is a user's guide, while the former explain the coding too, 
are about the whys-and-hows, about insights and hindsights.
However, remember that PWT is not an introduction to \TeX{} 
nor a treatise on macro writing.

PWT has been available in February {\oldstyle 1995}, in English.
A version in Russian is scheduled to be released
before Euro\TeX\ {\oldstyle95}, and CyrTUG {\oldstyle95}.
For the latter I'm dependent on my host for my various stays in Moscow,
Irina Gorbunova%\the\translator
, who volunteered to translate the work.

My aim has been to make PWT as useful as possible, 
even for those who don't intend to use \bluetex. 
Numerous examples show how to mark up in \TeX{} 
various typographic challenges known in the computer-assisted
information processing and dissemination world.
The above does not imply that the PWT script can't be printed.
No, not at all, it can, and you will  be surprised, hopefully, by the 
thin booklet of {\oldstyle125} odd pages, 
which will come off your selfpublishing press, some day.

I strove for a logically and physically thin system. The user's guide
is physically thin and even thinner logically. If you are not interested
in the math markup, just skip the chapter. Within a chapter examples
can be skipped of course. The chapters are independent with `thin'
interrelations. The files, especially the databases, allow you to 
load only what you need.

The layout has been kept simple. The page width has been determined by my
MAC screen. A large page length is there to reduce the number of
pages and to prevent underfull vboxes. The primary medium is a file,
not a book.

For future releases, I intend to include `markup pearls' from readers.
In the meantime, I'm pondering about hyperlinking the script to the
\TeX book script, and acquainting myself with \MF{} and 
{\manual META}\-{\smc post}. 
Another challenge, but fun. 
For the time-being, a printed version of PWT,
with the \TeX book at your elbow, or with windows open 
on each of the files needed, will hopefully ease your \TeX ing task. 
If not, let me know\dots\thinspace And for the rest

\displaycenterline{let us \TeX{} with confidence}

I hope that my approach to publishing with \TeX
\Dash a result of some {\oldstyle7} years of \TeX{} use and of some
  {\oldstyle20} years of programming numerical software\Dash
will be beneficial to new and old \AllTeX ies alike.
\bigskip
\rightline{Kees van der Laan}
\endpreface
                                    %Contents Page data
                                    %Because of \valign use, \contents{...}
\let\he\quad \let\she\qquad\def\sshe{\qquad\quad}%not possible.
\begincontents
Preface
Table of contents
Introduction
\he Understanding Knuth's markup
\he BLUe's format
\she The syntax
\she Variants
\he The Model
\he Notations and definitions
\he Markup conventions adopted
\he Copyrights BLUe's format
\separator 
Text 
\he Introduction
\he  Headings
\he Paragraphs
\she Parameterization
\she Special paragraphs
\she Customization 
\he Use of special text elements
\she Items
\she Centering
\she Quotations
\she Non-centered displays
\she Setting text apart
\she Pascal programs
\she Syntax diagrams
\she Verbatims
\she Exercises and answers
\she Footnotes
\he Fonts and size switching
\he Table of Contents
\separator 
Mathematics
\he What is the problem, Doc?
\he The extras
\he Use
\she Plain's display maths
\she A snapshot of examples
\separator 
Tabular material
\he Bordered table
\she Model
\she Markup tags
\she Customization
\he Use of btable macro
\he Kaleidoscope
\she Font charts
\separator 
Pictures
\he The roots
\he Creating pictures
\she Turtle Graphics
\she \TeX's stacking of boxes
\she Samplebox diversions
\she Picture environment
%
\newcol
%
\sshe Line thickness
\sshe Picture objects
\sshe Curves
\he Adding a picture to pic.dat
\he Using pictures
\he Fractals
\separator 
Coping with References
\he Using references
\he Cross-referencing
\he Adding a reference to lit.dat
\he Customization
\separator 
Creating an Index
\he Use
\he Markup of IR-s
\she Syntax
\she Markup
\she Spaces
\he Special tokens
\she Sorting keys
\he Ordering
\he Typesetting the index
\he Customization
\she Adding tokens to be ignored
\she Modifying ordering
\she Enriching the index
\she Typesetting the enriched file
\she Processes and files
\separator 
Customization
\he Changing look-and-feel
\she The page size
\she The header and footer
\she Section beginnings
\he BLUe script into MAPS
\he Other languages
\separator 
Afterthoughts
\separator 
Appendices
A: Answers to the exercises
B: Formats
\she      Use
\she      Concert
\she      Letter
\she      Report
\she      Transparencies
C: Tools
D: BLUe's, BLUes and Paradigms
E: List of Examples
F: Main Tags
G: Obsolete database
H: History of Changes
I: Index
J: Table of Contents
\endcontents

\let\backcover\pwtbackcover
\beginscript                        %BLUe script proper
%The next three have been included in 
%\report to facilitate mini-ToCs
%\immediate\openout\ans=answers
%\immediate\openout\toe=examples
%\immediate\openout\toc=contents
\input pwt.int %Introduction
%\pasteuptoe\pasteuptoc\endscript %test probe
\input pwt.txt %Text
%\setupappendices\pasteupanswers
%\sortindex\pasteupindex%\pasteuptoc%\endscript 
\input pwt.mat %Mathematics
\input pwt.tab %Tabular material
\input pwt.grf %Pictures
\input pwt.ref %References
\input pwt.ind %Index preparation
\input pwt.cus %Customization
\input pwt.aft %Afterthoughts
%From now on A, B, C,...
%And in order not to disturb the current
%number, and its use
\setupappendices
\pasteupanswers
\input pwt.fmt %B: Formats
\input pwt.tls %C: Tools
\input pwt.sur %D: Backgrounds
               %E: Table of examples
\pasteuptoe
\input pwt.tot %F: Table of tags
\input pwt.his %G: History of changes
\input pwt.obs %H: Obsolete macros
               %I: Index
\sortindex
\preindex\ea{\the\preindex
    In this index  \cs{end}$<tag>$s 
    have been excluded, only the \cs{begin}$<tag>$s are there.}
\pasteupindex
               %J: Table of contents
\pasteuptoc
\let\backcover\pwtbackcover
\endscript