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

\input blue.tex \loadindexmacros \loadsmileys \report 
                \hfuzz=25pt\vbadness=1000 

\bluechapter Text

\beginsummary
An introduction to the markup of text has been  given.
BLUe's format structure of text is nested to three levels, 
each preceded by a title. 
The building block is a paragraph.
The markup for \TeX's standard paragraph shape, 
the markup for the headings and 
the markup for some special text elements have been given.
Examples of the latter are:
items, 
quotations, 
display text, 
centering,
text to be set apart preceded and followed by lines, 
PASCAL programs,
verbatims,
exercises and answers, and 
footnotes.
\endsummary

\bluehead Introduction

Let us assume that we have ordinary text, to be typeset by computer. 
What to do? Let us begin by the beginning and write it down. 
\begincenterverbatim
An unexpected party

In a hole in the ground there lived a hobbit. 
Not a nasty, dirty, wet hole filled with the ends
of worms and an oozy smell, nor yet a dry, bare 
sandy hole with nothing in it to sit down on or 
to eat: 
it was a hobbit-hole and that means comfort.

It had a perfectly round door like a porthole,
painted green,...
!endcenterverbatim
We must instruct the computer\Dash that is, supply markup\Dash
to make something nice out of it. How?

As far as I understand it, ^{Knuth's\ markup} comes down to
just preceding the title by \cs{beginchapter}?!?
That is all. He makes use of the already available
visual markup of blank lines. These blank lines
separate document parts, be it a title from the text
or paragraphs from each other. 

Is that all? Essentially, yes. But\Dash there is always a but\Dash
the role which \cs{beginchapter} has to play is not simple. 
Happily, that is not our concern. That is the job of
the book designer in cooperation with the programmer.
I take for granted the niceties of \TeX's text processing\Dash 
and which a regular user tends to forget\Dash
such as automatic handling of ligatures, 
justification and hyphenation over paragraphs, and 
ignoring of superfluous blanks (spaces  and lines) in text.
All this is not necessarily restricted to English.

However, to quote {\TB} `and when you are using plain {\TeX} format, 
   you need to know that the ten characters
\begincenterverbatim
\ { } $ & # ^ _ % ~
!endcenterverbatim
cannot be used in the ordinary way when you are typing; each of them
will cause {\TeX} to do something special, \dots'

After this oversimplification let us go back to BLUe scripts,
full of the right spirit.

\bluehead BLUe script

BLUe's format allows text in print to be nested up to {\oldstyle3} levels deep.
The layout of the titles and the shapes of the paragraphs
contribute much to the look-and-feel.
The nesting is reflected in the markup tags 
\cs{head}, \cs{subhead} and \cs{subsubhead}.
Also \cs{title} and \cs{subtitle} are there.
The tag \cs{author} has been filled-in by default, 
meaning that you don't have to pay attention to it. 
It's {\em your\/} format.
You are Ben Lee User. 

\bluehead Headings

As a tribute to ^{manmac}, BLUe's format provides the following
outer level markup tags as an extra user-interface 
on top of the rigorous two-part macros.
\begincenterverbatim
\blue(sub)title <(sub)titletext>                    

\bluekeywords <listofkeywords>            

\blue(sub(sub))head <(sub(sub))sectionheadtext> 
           
\blueexample <exampleheadtext>            
!endcenterverbatim
A handful, but\Dash there is always a but\Dash the ^{processing on the fly} 
has been lost.
Note that all have a blank line\Dash implicit markup\Dash or 
\cs{par} as end separator. Reread page {\oldstyle202} of \TB, please.
I used them in this script, because they counter the ^{curly braces mania},
or to put it in Knuth's words 
\displaycenterline{`\dots you needn't always enclose arguments in braces.'}

^^{heading,\ markup}
The regular markup for headings reads as follows.\ftn{Of course the long forms
   |\begin<tag>| and |\end<tag>| can be used too.}
\displaycenterline{|\head{<headtext>}|}
Similar for \cs{subhead} and \cs{subsubhead}. 
No terminating periods are  automatically typeset.

\bluesubhead Parameterization 

The text of a heading is preceded by \cs{prehead} and followed by \cs{posthead}. 
Again, similarly for \cs{subhead} and \cs{subsubhead}.
By default the placement within context\Dash that is,
the tokens contained in |\pre<tag>|  and |\post<tag>|\Dash
is determined by the following, apart from (stretchable) glue.\ftn{See for 
   those \TB{}{\oldstyle355}, especially \cs{beginsection}. `The macro first emits glue
   and penalties designed to start a new page if the present page is nearly
   full, \dots' This mechanism has been borrowed for the various
   |\pre(sub(sub))head|-s.} 
The latter fills up the page by a page break 
to prevent an underfull \cs{vbox} message.

{\let\css\cs
\def\rowstblst{{\css{head}}{\css{sh}}{\css{ssh}}}
\def\data{\css{bigskip}                               \cs\css{nobreak}\css{medskip}\css{noindent}\rs
          \css{medbreak}\css{noindent}\css{shindent}   \cs\css{quad}\rs
          \css{smallbreak}\css{noindent}\css{sshindent}\cs\css{quad}\rs}
\def\rowstbsep{\quad}
\def\tag{${<}tag{>}$}
\def\first{\css{}\tag}
\def\header{\css{}pre\tag\cs \css{}post\tag}
\def\footer{{\small*sh stands for subhead, ssh for subsubhead}}
\def\headersep{\kern.5ex\hrule\kern.75ex}
$$\fll\btable\data$$}

With defaults \cs{subheadindent}{\oldstyle0}pt and 
\cs{subsubheadindent}\cs{generalindent}.
I used to mark up headings by the short form, i.e.,
by |\head{...}| instead of ^|\beginhead| \dots \cs{endhead}.
From now on\Dash back to the roots\Dash I will use manmac's minimal forms.
In headings I don't need much processing on the fly.

Automatic numbering is provided in the \cs{report} format.
The idea is to use  |\<tag>numbering| token variables.

The above is only part of the story, just the top of the iceberg
In a document we also like to reuse the head titles for table of contents,
the index, and undoubtedly we need the head numbers sooner or later,
whether they are hidden or not. 
So on the one hand we like to process a title on the fly, and 
on the other hand we like to store head information, as general as possible,
for reuse. 
In the \cs{report} format I had to face the music and deal with those issues. 
Happily, the  {\bluetex} kernel could do without it.
^^{heading,\ automatic numbering}

\bluehead Paragraphs

\TeX's building block is the ^{paragraph}. 
This unit is split up into lines to be mapped on pages.
The markup for a  paragraph is minimal, i.e., 
it is generally implicit and near to natural.
An occasional user is hardly aware of the markup.
In most cases 
\begincenterblock
a paragraph starts by the first letter, and 
ends by a blank line. 
\endcenterblock
The blank line is substituted by \cs{par} automatically.
Explicit markup for a paragraph reads
\begincenterverbatim
\indent  %starts a paragraph, an empty box (size \parindent) is inserted 
         %or \noindent, which just starts a paragraph
<paragraph>
\par     %ends the paragraph, and resets defaults of par shape pars
         %\hangindent and \hangafter
!endcenterverbatim
On encountering a vertical command in a paragraph,
like \cs{smallskip} and its ilks,
\TeX{} automatically inserts \cs{par}, and because of this
the paragraph is ended. 
Each script, and this one is no exception, contains a lot of
ordinary paragraphs.\ftn{For an extensive treatment of paragraphs see
   {\TB} chapter~{\oldstyle14}.}

\bluesubhead Parameterization

The parameters which govern the standard paragraph shape are given in the
following model.\ftn{Courtesy David Salomon. (A white lie, any 
   migrated vertical material has been omitted.)}
\def\Xfil{\xleaders\hbox{X}\hfil}
\beginquote\advance\leftskip.25\hsize
           \advance\rightskip.25\hsize\small\noindent
\hfil\cs{parskip}\\\null
\hfil\cs{(base)lineskip}\\\null
\cs{parindent}\Xfil\break\null
\hfil\cs{clubpenalty}\\\null
\hfil\cs{(base)lineskip}\\\null
\Xfil\break\null
\hfil\cs{interlinepenalty}\\\null
\hfil\cs{(base)lineskip}\\\null
\hfil$\vdots$\\\null
\Xfil\break\null
\hfil\cs{widowpenalty}\\\null
\hfil\cs{(base)lineskip}\\\null
\Xfil\cs{parfillskip}\break\null
$\longleftarrow$\hfill\cs{hsize}\hfill$\longrightarrow$
\endquote
The left margin is \cs{hoffset} from the left.
The distance from the left side of the paragraph 
to the left margin is the glue \cs{leftskip}. 
At the right side the glue has the name \cs{rightskip}.
Between words the glue is \cs{spaceskip} and between
sentences \cs{xspaceskip}. 

The contents of the token variable \cs{everypar} is inserted before
the paragraph text. 

\exercise How can the parameters be set such that the last line
          of a paragraph is centered\ftn{Courtesy Anne Br\"uggeman-Klein.}?
\answer \cs{leftskip}0pt plus1fil, 
        \cs{rightskip}0pt plus$-1$fil,
        and \cs{parfillskip}0pt plus2fil.
        End the paragraph with |\hskip0pt plus1fil|.

\exercise One of the problems induced by paragraphs as building blocks is that
          it is not easy to provide for line numbering. 
          How can we achieve this\ftn{Courtesy Jan Kybic.}? 
\answer Jan Kybic reported about the several ways  he received as answers
        to this problem on comp.text.tex.
        Below is the solution due to Petr Olsak. Beware it is limited.
        The general idea in the solutions collected by Kybic
        is to take apart the lines set in a vbox either
        starting at the end via \cs{lastbox} or starting at the begin
        via \cs{vsplit}, collect these
        lines extended by their line numbers, and reinsert these later.
       \beginverbatim
%Due to Petr Olsak
%Disclaimer: Macros for plain prose line 
%numbering only for ordinary paragraphs 
%without display mathematics or other
%specialities. 
%(Note added: no \footnote, \centerline.)
\newcount\linenum
\newcount\worknum
\newbox\allparagraph
\def\beginnum{\begingroup\linenum0 
   \def\par{\ifhmode\completepar\fi}%
   \setbox\allparagraph\vbox\bgroup}
%
\def\endnum{\par\egroup\endgroup}
%
\def\completepar{\endgraf \global
   \advance\linenum\prevgraf
   \worknum\linenum \setbox0\null
   \loop\unskip\unpenalty
     \setbox2\lastbox 
     \ifhbox2 \global\setbox0\hbox
      {\llap{$\scriptstyle\the\worknum.$ 
             }\box2\penalty0\unhbox0}%
      \advance\worknum-1
   \repeat\egroup\noindent
   \unhbox0\unpenalty\endgraf
   \setbox\allparagraph\vbox\bgroup}
!endverbatim
The numbering of verbatim lines has been treated separately. 
Another variant is mentioned by Salomon to number the lines on 
{\it each page}. 
This is handy for proofers to indicate more precisely the commented parts. 
See his OTR articles as published in \TUB
\Dash or his courseware `Insights \& Hindsights' 
      MAPS Special {\oldstyle1992}\Dash 
for the modified OTR. 
Knuth in \tubissue8(2) {\oldstyle1987}\Dash about letting text
flow around figures\Dash provided the basics for
Hoenig's approach \tubissue{15}(3) {\oldstyle1994}, to let the OTR 
create one-line pages\Dash i.e., one can lay hands on each line\Dash 
and introduce a `mock'-\cs{everyline}. Promising. 


\bluesubhead Why a paragraph as unit for line breaking?

Knuth did choose a paragraph as next larger unit than a line for line
breaking, i.e., for mapping the horizontal list onto lines.
This gives better results than using roughly a line.

\exercise What happens to accented words?
\answer They  hyphenate, but only the part of the word up to the accent control
        sequence is subject to hyphenation as such.
        However, we can do much better and
        use \cs{allowhyphens}\Dash from Appendix~D
        {\sl Hanging punctuation}\Dash to be inserted after the place
        where the hyphenation stopped. The conclusion is that \TeX{}
        can hyphenate properly accented words.
        For example the Dutch word
        `|onge\"emancipeerde|' can better be input as `|onge\ee{}mancipeerde|'
        with\ftn{Courtesy Bernd Raichle and Bas Romeny, 
                 and a wink to dutch.sty.}
\beginverbatim
\def\ee{\nobreak\discretionary{e-}{e}{\"e}\allowhyphens}
\newskip\zzz\def\allowhyphens{\nobreak\hskip\zzz}
\hyphenation{man-ci-peer-de}
!endverbatim
Note that because of the Dutch rules with respect to a dieresis
use has to be made of \cs{discretionary} as well.
The explanation is that the search for hyphenation patterns is stopped
when an explicit kern, induced by the accent, is encountered. 
To let \TeX{} resume hyphenation of the remainder 
the zero glue \cs{hskip} is inserted. A line break is inhibited
by \cs{nobreak}. The first \cs{nobreak} is needed to isolate the effect
of the \cs{discretionary}. Normally when a discretionary is encountered
\TeX{} stops hyphenating the complete word.
       

\exercise What is wrong with |pretext\par\llap`Quotation'|?
\answer \cs{llap} does not start the horizontal mode. Insert \cs{leavevmode}
        after \cs{par}.

\exercise What is the unexpected result of |\par{\bf New paragraph} blah blah| 
          with |\everypar{\hang}| active\ftn{Courtesy Alan Reese}? 
          And why?\ftn{Courtesy Jeremy Henty.}
          Note that \cs{bf} is only there to make the pitfall look
          realistic.
\answer Without braces the text comes out as a block. With the braces at the 
        beginning there is no effect of the automatically inserted \cs{hang}.
        The explanantion reads as follows.
        When processing ordinary text, \TeX{} does not enter horizontal mode
        until it encounters a letter. In the troublesome paragraph the first
        letter is inside a group. When the group ends all local assignments 
        are undone, and the effect of the \cs{hang} instruction\Dash 
        the contents of \cs{everypar} is inserted within the group\Dash
        is forgotten. 
        A solution is to precede the group by \cs{leavevmode},
        because the \cs{everypar} will be executed before the group then.


\exercise How can we allow for hyphenation in teletype font?
\answer This is handy when we set control sequences in \cs{tt}
        in two-column. Provide
\beginverbatim
\hyphenchar\tentt=`-
!endverbatim

\exercise And what about page breaks?
\answer The fact is that Knuth did not implement a spread or a chapter
   as next larger unit than a little more than `a page' for page breaking,
   i.e., for mapping the main vertical list onto pages.
   Perhaps this was dictated by the status of the hardware technology
   when \TeX{} was designed.

\noindent The ^{hyphenation} process can be customized  by
\beginverbatim
\lefthyphenmin=<number>    \righthyphenmin=<number> 
!endverbatim
which are {\oldstyle2} and {\oldstyle3} by default, 
and via exceptions as argument to
\cs{hyphenation}. For \TB{} Knuth used as exceptions
\beginverbatim
\hyphenation{man-u-script man-u-scripts ap-pen-dix}
!endverbatim
Hyphenation assignments are global and cumulative.
For more details start with Appendix~H of \TB.

\bluesubhead Special paragraphs

\TeX{} provides \cs{parshape}, \cs{hangindent} and \cs{hangafter}
for special paragraph shapes. A captivating example is provided
in \TB{} {\oldstyle101}.

\blueexample Miniature

History has it to start the first paragraph of a chapter 
with a `Miniature.' ^^{miniature} 
Knuth in his `Preface' showed how to mark up such kinds of paragraphs. 
This is an illustration of the use
of \cs{hangindent}\ftn{\cs{hang} assigns the value
   of \cs{parindent} to \cs{hangindent}.}
and \cs{hangafter}, as well as of the use of
\cs{smash} outside math mode.
There is no need for a special `^{dropped capital}' macro, because it is
really simple. 

\cs{cglpic} is the minitiature used from the picture database pic.dat.
For an nice application\ftn{Courtesy Huub Mulders.} see the miniature in the
NTG information, on the inside of the back cover.\ftn{Knuth in \tubissue8(2), 
    {\oldstyle1987}, touched upon the  general problem how to 
     let text {\it flow around\/} figures. 
     Hoenig \tubissue{15}(3), {\oldstyle1994}, provided user-friendly macros.}
\begindemo
\pictures{\gpic}%load gpic
\parindent=24pt
\noindent\hang\hangafter-2
\smash{\lower13pt\hbox to0pt{%
\hskip-\hangindent\gpic
\hfil}}{\smc entle Reader}: 
This is a handbook about \TeX, 
a new typesetting system 
intended for the creation of 
beautiful books\Dash and 
especially for books that 
containa lot of mathematics. 
!yields
\pictures{\gpic}
\parindent=24pt
\noindent\hangindent\parindent
\hangafter-2
\smash{\lower13pt\hbox to0pt{\hskip
 -\hangindent\gpic\hfil}}{\smc entle Reader}: 
This is a handbook about \TeX, 
a new typesetting 
system intended for the creation of beautiful 
books\Dash and especially for books that contain
a lot of mathematics. 
\par\noindent
\enddemo

Remark. Realize that the reference point for the \cs{smash}
   is where the {\smc e} starts, and that the first ({\oldstyle2}) lines are 
   indented.
   Within the \cs{smash} you can move around as you wish, leaving the
   reference point and the other things outside invariant.  
Note the use of \cs{smc} to smooth the transition from the miniature to the
rest of the text.

\exercise Compare the above simplified version of Knuth's opening
   sentence with the real one in \TB{} script.

\exercise At the end of each paragraph \TeX{} resets the paragraph shape
          parameters. How can we retain these values\ftn{Courtesy
             Marek Ry\'cko and Bogus{\l}aw Jackowski.}?
\answer Use |{\par}| instead of \cs{par}. See
        their article `From \cs{indent} to \cs{par},'
        MAPS{\oldstyle94}.{\oldstyle2}, among other things. 
        The point is they are changed, but\Dash
        there is always a but\Dash on encountering
        a \cs{par} the paragraph shape parameters are reset {\sl locally},
        within the group so to say. 
        After the group closing, the right curly brace, 
        the old values pop up again, which  yields the effect.
        Note. This method was first elucidated by the author of \TeX{}
        and communicated in a private letter to Elizabeth Barnhart, of 
        {\oldstyle1987}.


\exercise Is the scope of \cs{leftskip} and \cs{rightskip} restricted 
          to a paragraph?
\answer No, it is not.

\blueexample Flushed right paragraphs

At the end of each chapter in \TB{}
quotations are set as flushed paragraphs. ^^{paragraphs,\ flushed}
A little simplified the following will
do the job. The key issue is the
use of \cs{leftskip} and the zero value
of \cs{rightskip} and \cs{parfillskip}.
\cs{manmacauthor} is the \cs{author} macro from manmac to
set the author part in those quotations.

\begindemo
\leftskip0pt plus40pc 
             minus\parindent 
\rightskip0pt\parfillskip0pt
\everypar{\sl}\obeylines
I got the BLUes,
but I like it
\manmacauthor{Anonymous}
             (20th Century) 
\bigskip
It contains all
\manmacauthor{DeK}(1978) \TB
!yields
\leftskip 0pt plus 40pc minus\parindent
\rightskip0pt\parfillskip0pt
\everypar{\sl}\obeylines
I got the BLUes,
but I like it
\manmacauthor{Anonymous}(20th Century) 
\bigskip
It contains all
\manmacauthor{DeK}(1978) \TB
\enddemo

\exercise Why is |\everypar{\sl}| needed, instead of just \cs{sl}\ftn{Courtesy
               Staszek Wawrykiewicz}?
\answer  In \cs{manmacauthor} \cs{rm} is switched on for the special
         paragraph of the author line.  
         The next quotation, if there is one, takes \cs{sl} again, automatically.
         Note that the \cs{noindent} in \cs{manmacauthor} is mandatory,
         because it starts the new paragraph and therefore \cs{rm} will
         be in effect. It will come after the automatically inserted
         \cs{sl}. 

\bluesubhead Customization
 
The hook for customization of paragraphs is
the token variable \cs{everypar}.
A nice application of \cs{everypar}, next to \cs{sl} above,
is to number lines automatically in verbatim texts.

\bluehead Accents and ligatures

Some ligatures come automatically while others have to marked up for.
\begindemo
TB ex9.2-3
{\AE}sop's {\OE}uvres en fran\c cais\\
p\^at\'es
!yields
$$\hbox{{\AE}sop's {\OE}uvres en fran\c cais}$$
$$\hbox{p\^at\'es}$$
\enddemo 
Remark. From \TB~{\oldstyle54}. \dots`It's important to remember that these
conventions for ^{accents} and special letters are not built into {\TeX} itself;
they belong to the plain {\TeX} format, which uses the Computer Modern fonts.'

\bluehead Paragraphs with digits

^^{numbers in paragraphs}
When numbers occur in paragraphs they look irregular, they exceed the size
of lowercase letters. Typographers advise to use \cs{oldstyle}.
Minimal markup can be achieved via \cs{on}, for example |\on3|.\ftn{When a space
should follow the number end the number by |{}|{\tt\char32}.} 

\bluehead Use of special text elements
 
Examples of special text elements are:
 items, labeled by a bullet, by a number, or alphabetically;
 centering,
 quotations;
 (non-centered) displays; 
 text to be set apart, preceded and followed by a line;
 PASCAL text; 
 syntax diagrams; 
 verbatims;
 exercises and answers; and
 footnotes.

The markup for these elements will be shown by examples.

\bluesubhead Items

At the basis are plain's one-parameter \cs{item} and \cs{itemitem},
which take as argument the item marker. 
The bulleted item, ^|\bitem|, comes from \TB{} ex{\oldstyle14}.{\oldstyle20}. 
^|\nitem|\Dash numbered items\Dash
^|\aitem|\Dash alphabetically labeled items, lowercase\Dash  
^|\Aitem|\Dash alphabetically labeled items, uppercase\Dash and
^|\eitem|\Dash enumerated items,
are similar extensions. 
The extensions provide the marker automatically, no argument is needed. 
Note that the closing tag is \cs{smallbreak}.\ftn{Knuth advised \cs{medskip}
   before and after, \TB{} {\oldstyle102}. I sobered this and made use of
   \cs{smallbreak}'s paragraph terminating function.}

\blueexample Items

\begindemo
\bitem first item
\itemitem{--} subitem
\bitem second item
\smallbreak
!yields
{\parindent=1pc
\bitem first item
\itemitem{--} subitem
\bitem second item
\smallbreak}
\enddemo

\bluesubhead Quotations

A special case of centering a block is the so-called quotation, indented
on the left and the right by the same (fixed) amount, usually the value
of \cs{parindent}. ^^|\beginquote|

\blueexample Quotations

\begindemo
pretext
\beginquote
Some text to be set apart, 
indented on the left and 
on the right 
\endquote
posttext
!yields
pretext
\beginquote
Some text to be set apart,
indented on the left and on the right. 
\endquote posttext
\enddemo
Add a little to this to obtain \cs{beginsummary} and
\cs{endsummary}, abstracting in the markup from formatting details.
A step towards descriptive or functional markup. The summaries
at the beginning of each chapter of PWT have been marked up in this way.
Perhaps it is also good to mention here that accents don't start horizontal
mode. If you like to quote then start with \cs{leavevmode}\Dash to enforce
horizontal mode\Dash followed by  |\llap`| or so.

\bluesubhead Setting text apart

^|\beginlines| and |\endlines|, \TB{} {\oldstyle583}--{\oldstyle591}, 
is in display (zero-indented),
which obeys the line structure and inserts a \cs{hrule} for and aft.  
For an example of use I borrowed the following from \TB, where it is
used in combination with in-line verbatim.
\cs{obeylines} is on.\ftn{Variant \cs{endlines} are
   \cs{weak\-end\-li\-nes}, \cs{fi\-nal\-end\-li\-nes}. 
   The former uses a \cs{medskip} instead of a \cs{medbreak}.}

\blueexample Setting text apart

\thisverbatim{\catcode`\|=12 }
\begindemo
%TB 343    
\beginlines
|%This is the plain TeX format |
|%that's described in The TeXbook.|
\dots
\endlines
!yields
\beginlines
|%This is the plain TeX format|
|%that's described in The TeXbook.|
\dots
\endlines
\enddemo

\bluesubhead Centering in display

Plain \TeX{} provides \cs{centerline}.
BLUe's format provides the extension ^|\displaycenterline|, 
to center a line with display glue for and aft, and
^|\begincenter| \dots \cs{endcenter}, and ^|\begincenterblock| \dots 
\cs{endcenterblock} to center each line of the block. 
^^|\begincenterdisplay|

\blueexample Centering in display

\begindemo
pretext
\displaycenterline{I $\heartsuit$ 
                   \TeX{} \winksmiley}
text in between
\begincenterblock
Sign of times?
The extraordinary rate of change.
\endcenterblock
intermediate text
\begincenter
TLC
tender loving care
that is all there is
\endcenter
posttext
!yields
pretext
\displaycenterline{I $\heartsuit$ \TeX{} \winksmiley}
text in between
\begincenterblock
Sign of times?
The extraordinary rate of change.
\endcenterblock
intermediate text
\begincenter
TLC
tender loving care
that is all there is
\endcenter
posttext
\enddemo
Remarks. 
Agreed, \cs{displaycenterline} is a special case and therefore superfluous.
An alternative for centering of a block\Dash although a little different\Dash
is \cs{raggedcenter}
`that partitions the words of a paragraph into as few as possible lines
 of approximately equal size and centers each individual line.
 Hyphenation should be avoided if possible.'
{\TB} ex{\oldstyle14}.{\oldstyle34}.

\exercise Do |\begincenter...\endcenter| and 
|\begincenterblock...\endcenterblock| allow for page breaks?
\answer |\begincenter...\endcenter| does. 
        |\begincenterblock...\endcenterblock| does not, 
        because it is a \cs{vbox}.

\bluesubhead Non-centered displays: one-line, multi-lines and multi-columns

^|\begindisplay| and |\enddisplay|, \TB{} {\oldstyle434}--{\oldstyle439}, 
yields an indented display. Very powerful and user-friendly.

\blueexample Non-centered displays: one-line, multi-lines and multi-columns

\begindemo
pretext
%TB 3
\begindisplay
   ``I understand.''
\enddisplay
posttext
!yields
pretext\begindisplay
   ``I understand.''
\enddisplay posttext
\enddemo

Multi-line displays can be handled by ending each line 
in the environment by the control sequence \cs{cr}. ^^{multi-line displays}
The indentation is the value of \cs{displayindent},
default {\oldstyle0}pt, next to the |\hbox to\parindent{}| because of the
\cs{indent} in the (hidden) template.

\begindemo
pretext
%TB 4
\begindisplay
   a hyphen (-);\cr
   an en-dash (--);\cr
   an em-dash (---);\cr
   a minus sign ($-$).\cr
\enddisplay
posttext
!yields
pretext
\begindisplay
   a hyphen (-);\cr
   an en-dash (--);\cr
   an em-dash (---);\cr
   a minus sign ($-$).\cr
\enddisplay
posttext
\enddemo

Another subtle point is that more-column copy can be displayed,
because a repetitive template has been used.

\begindemo
pretext
%TB 29
\begindisplay \hbadness10000
 \hbox spread-.666667em{The
 badness of this line is 100.}&
           (very tight)\cr
 \hbox spread-.333333em{The 
 badness of this line is 12.}&
      (somewhat tight)\cr
 ...
\enddisplay
posttext
!yields
pretext
\begindisplay \hbadness10000
 \hbox spread-.666667em{The
 badness of this line is 100.}&
           \ (very tight)\cr
 \hbox spread-.333333em{The 
 badness of this line is 12.}&
      \ (somewhat tight)\cr
      ...
\enddisplay 
posttext
\enddemo

\exercise How can we center a \cs{begindisplay}\dots \cs{enddisplay}?
\answer Enclosing the construct with a \cs{vbox} in math display does
        not work, which is the usual way to center a \cs{halign}.
        This comes from the fact that the construct is recognized as an
        alignment display. A solution is
\beginverbatim
{\def\enddisplay{\crcr\egroup\egroup$$}
  \begindisplay\vbox\bgroup
  <displaymaterial>
  \enddisplay}
!endverbatim
Perhaps it is simpler for those cases to fall back on the following 
usual markup
\beginverbatim
$$\vbox{\halign{<template>
  <displaymaterial>
  }}$$
!endverbatim

%end answer
\bluesubhead Syntax diagrams

Markup tags are 
\begincenterdisplay
^|\beginsyntax|\dots |\endsyntax| &the environment\cr
^|\alt|                           &to start an alternative\cr 
^|\is|                            &to define left element\cr
\thisverbatim{\unmc}|<| and \thisverbatim{\unmc}|>|  
                                  &to start and end a unit.\cr
\endcenterdisplay
When a line starts with 
\thisverbatim{\unmc}|<| it is assumed
that a new rule starts. \cs{obeylines} is on.
The end-of-line is redefined to take the appropriate action.
In the example below a \cs{quad} is
used in the markup to prevent starting a new rule.
The \% sign at the end of a line annihilates the effect of
the e-o-l, and prevents a new rule to start. 

\blueexample Syntax diagrams

\thisverbatim{\unmc}
\begindemo
%TB 268
\beginsyntax
<unitofmeasure>\is
\quad<optionalspaces>%
       <internalunit>
\alt<optional {\tt true}>%
          <physicalunit>
\endsyntax
!yields
\beginsyntax
<unit of measure>\is
\quad<optionalspaces><internalunit>
\alt<optional {\tt true}><physicalunit>
\endsyntax
\enddemo

\bluesubhead Programs
 
Program texts are special, due to the use of non-monospaced fonts.
\bluetex{} assumes that the ^{PASCAL texts} have been prepared in such
a way that they are insensitive to font spacing.\ftn{Courtesy Wilson 
     and Addyman. Compare the markup with \TB{} {\oldstyle234} and 
      ex{\oldstyle18}.{\oldstyle9}, 
     and you will appreciate
     the approach of  BLUe's format typesetting of PASCAL.}
^^|\beginpascal|

\blueexample Programs

\begindemo
\beginpascal
(*Print length of third side of 
 triangle given two sides and 
 enclosed angle*)
program EX4A(input, output);
var a, b, c angle : real;
begin read(a, b, angle);
   c:=sqrt(sqr(a)+sqr(b)-
                2*a*b*cos(angle));
   writeln('The third side is', c)
end.
\endpascal
!yields
\beginpascal
(*Print length of third side of 
 triangle given two sides and 
 enclosed angle*)
program EX4A(input, output);
var a, b, c, angle : real;
begin read(a, b, angle);
   c:=sqrt(sqr(a)+sqr(b)-
                2*a*b*cos(angle));
   writeln('The third side is', c)
end.
\endpascal
\enddemo

Perhaps it is not nice to have the types in the same font as variables. 
PASCAL can be extended with types, 
and therefore names of types are also variable.
An open problem is the vertical alignment because of the monotype fonts in the input
and the variable-width fonts used in the typeset result. Proofing needed.

\exercise How can we use the macros for typesetting program fragments
          in other languages?
\answer The set of reserved words has to be customized, next to
        the handling of special symbols.

%end exercise

\bluesubhead Verbatims
 
The functionalities are ^{verbatim\ text} (in-line and in display), 
and file verbatim inclusion.

The markup starts with ^|\beginverbatim| and ends with 
^|<escapechar>endverbatim|. The default escape character is `!'.
`Options,' for among other things numbering and enabling of metacode,
are handled via the token variables
\cs{thisverbatim}, or globally via \cs{everyverbatim}.

The place within context is controlled via 
the token variables ^|\preverbatim| and ^|\postverbatim|.

It is true that verbatims are  heavily used
by authors who write in \AllTeX{} about \AllTeX,
and perhaps not so relevant for math authors.

\blueexample Verbatims: escape char use
 
\thisverbatim{\catcode`\|=12 \let\-=-
              \catcode`\!=12
              \catcode`\<=12
              \catcode`\-=0 }
^^{verbatim,\ escape char}
\begindemo
%To handle via ! (escape char)  
%   -- other fonts 
%   -- emc (enable metacode)
\thisverbatim={\emc}
\beginverbatim 
Some <metacode> and
blah, blah, ...    !it
Now text in italics!tt
and back again in tt
!endverbatim
-yields
\thisverbatim={\emc}
\beginverbatim 
Some <metacode> and
blah, blah, ...    !it
Now text in italics!tt
and back again in tt
!endverbatim
\enddemo

\blueexample Verbatims: line numbering and file inclusion
 
\thisverbatim{\catcode`\|=12 
     \let\-=- \catcode`\!=12
              \catcode`\<=12
              \catcode`\-=0 }
^^{verbatim,\ line numbering}
^^{verbatim,\ file inclusion}
\begindemo
pretext
\everyverbatim={\numvrb}
\thisverbatim={%
   \catcode`\!=12 
   \catcode`\|=12 
%  \input vrb.tex %<file>
   \makeescape\*}%To terminate 
\beginverbatim 
Extras after file
*endverbatim
\noindent posttext
-yields\noindent
pretext
\everyverbatim={\numvrb}
\thisverbatim={\emc
   \catcode`\!=12 
   \catcode`\|=12 
%  \input vrb.tex
   \makeescape\*}%To terminate 
\beginverbatim 
<file>
Extras after file*nonum
*endverbatim
\noindent posttext
\enddemo

\blueexample Verbatims: line numbering

\thisverbatim{\catcode`\|=12 
     \let\-=- \catcode`\!=12
              \catcode`\<=12
              \catcode`\-=0 }
\begindemo
\thisverbatim={\numvrb
               \catcode`\~=9 
               \catcode`\*=14 }
\beginverbatim 
Just some text with 
ligatures such as ?` switched 
off (TB 381).
line numbers restarted via
<escapechar>numvrb.!nonum
<escapechar>nonum switches off
line numbering.
<escapechar>vrblin<number> 
assigns
<number> to the line counter.


!numvrb~After two blank* 
lines.!nonum
!endverbatim
-yields
\thisverbatim={\numvrb
               \catcode`\~=9 
               \catcode`\*=14 }
\beginverbatim 
Just some text with 
ligatures such as ?` switched 
off (TB 381).
line numbers restarted via
<escapechar>numvrb.!nonum
<escapechar>nonum switches off
line numbering.
<escapechar>vrblin<number> assigns
<number> to the line counter.


!numvrb~After two blank* 
lines.!nonum
!endverbatim
\enddemo

\blueexample Verbatims: in line
 
\thisverbatim{\catcode`\|=12 
     \let\-=- %\catcode`\!=12
              \catcode`\<=12
              \catcode`\-=0 }
^^{verbatim,\ in-line}
{\def\-{\hbox{-}}
\begindemo
\thisverbatim{\emc}
Before |<in!-lineverbatim>| after.
-yields\indent
\thisverbatim{\emc}
Before |<in!-lineverbatim>| after.
\enddemo}
Also provided is \cs{unmc} to unable metacode.

For ^{long\ verbatim\ listing}s supply
\beginverbatim
\everyverbatim{\baselineskip12ptplus2ptminus1pt\lineskip1ptplus1ptminus1pt}
!endverbatim
to prevent underfull vbox messages.
\exercise How can we put \cs{it}, and \cs{tt} at the beginning of
          the lines?
\answer The naive way introduces an unwanted space. We can get rid of 
        a space after a control sequence via the use of a control symbol
        with category code 9 (to be ignored) after those control sequences.

\exercise How can we center verbatims? ^^|\begincenterverbatim|
\answer This is included in BLUe's format and reads as follows.
\thisverbatim{\catcode`\~=0 \catcode`\!=12 }
\beginverbatim
\def\boxlines{\obeyspaces\fifol}
%\gdef\fifol#1^^M{\ifx\lofif#1\lofif\fi
%  \processl{#1}\fifol}
\def\begincenterverbatim{$$%
   \def\processl##1{\hbox{##1}}%
   \def\lofif##1\fifol{\fi\egroup
     \egroup$$\thisverbatim{}}
   \let\endcenterverbatim\lofif
   \bgroup\tt\setupcopy
   \let\!=!\catcode`\!=0 
   \the\everyverbatim\the\thisverbatim
   \vbox\bgroup\boxlines}
~endverbatim

\exercise A math display does not end a paragraph, it is part of the
          paragraph with the effect that paragraph parameters
          are not reset to their defaults. What about \cs{beginverbatim}
          |!!endverbatim|?
\answer It looks although all depends on the values of \cs{preverbatim} and 
        \cs{postverbatim}. The defaults are \cs{medskip} and
        \cs{smallbreak}. The former does not insert a \cs{par}
        while the latter does. As is well-known a \cs{par} 
        terminates a paragraph. However, the subtleness is that
        \cs{begingroup} and \cs{endgroup} enclose the verbatim
        which, \TB{} 279 `don't change the mode.' On reading I did not
        understand the consequences of the  quoted sentence.
        A small experiment taught me that the paragraph parameters are not 
        reset. Therefore the \cs{beginverbatim} |<escapechar>endverbatim| 
        just {\it interrupt\/} the paragraph, similar to the math display.

%end exercise 

Remark. As known \TeX{} makes use of special characters. For example
when \% is input the \% is not obtained in print, but rather the rest of
the input line is considered as comment.
Similar for $<$, $>$ and \vrt{} in horizontal mode, although for a different reason.
Because of this the less than and greater than symbols can be used nicely 
for syntax charts and the vertical bar for in-line verbatim.

\bluesubsubhead Pitfalls

There are some pitfalls that I know of and that
a user might like to be aware of. ^^{verbatim,\ pitfalls}
\bitem Default \cs{emc} and when the less than and greater than signs are
       used curious error messages occur. Remedy |\thisverbatim{\unmc}|.
\bitem Long verbatims give a bunch of underfull vbox messages.
       Remedy |\everyverbatim{|\\
       |\baselineskip12pt plus2pt minus1pt|\\
       |\lineskip1ptplus1ptminus1pt}|
\bitem And \dots don't forget  ! is the default escape character.
!endverbatim
\smallbreak

\bluesubhead Exercise and answer

Exercises and answers have to be marked up as follows. 
\blueexample Exercise and answer

\begincenterverbatim
\exercise<exercisetext>
\answer<answertext>

%followed by a blank line
!endcenterverbatim

\bluesubhead Footnotes

Plain \TeX{} provides the \cs{footnote} command. ^^{footnote, 
   automatic numbering}
\TB{} ex{\oldstyle15}.{\oldstyle12} deals with how to number a footnote 
automatically.
In \bluetex{} the markup for the latter is ^|\ftn||{<footnotetext>}|. 

In the title part of an article\Dash or report\Dash
BLUe falls back on \cs{footnote}, because those footnotes 
are some sort of out of order. That use reads as follows.

\blueexample Footnotes

\begincenterverbatim
\footnote*{<titlefootnotetext>}
%or
\footnote{**}{<titlefootnotetext>}
%etc.
!endcenterverbatim
The above is regular \TeX. Because of me using \cs{oldstyle} for the numbering
the {\oldstyle*} symbol will be obtained instead of *. To correct this
provide |{\rm *}|, or just forget about a marker and provide an empty group.
From the context it is clear enough that the note is about the title.
The footnotes are set in {\oldstyle8}pt.

^^{margin notes}
\exercise And what about notes in the margin?
\answer This is not implemented in \bluetex's OTR.
        It is rather difficult to combine that with flexibility
        with the number of columns.
        If needed occasionally use \cs{vadjust}.

%end exercise

\bluehead Fonts and size switching

Default {\oldstyle10}pt is used. ^^{fonts\ and\ size\ switching\ macros}
For the moment I stay with Knuth and copied his size-switching 
macros.\ftn{Because of this attitude
   I could easily kameleon \cs{oldstyle} to all those sizes.
   To achieve this with NFSS would have cost me much more time, 
   I guess.} 
BLUe's format contains the size-switching macros 
\cs{Large}, $\approx$\thinspace{\oldstyle17}pt,  used for chapter headings,
\cs{large}, $\approx$\thinspace{\oldstyle14}.{\oldstyle5}pt, 
used for transparencies,
and \cs{small}, that is, {\oldstyle8}pt, used for footnotes. 
Next to these \cs{tenpoint}, \cs{ninepoint}, and
\cs{eightpoint} have been inherited from manmac. 

\cs{tiny} has size {\oldstyle5}pt and has been setup similar to the 
\cs{...type} macros from Knuth's concert format, Appendix~E of \TB. 
A pedagogical stepping stone for size-switching macros,
and sufficient for just text. 
\beginverbatim
\def\tiny{\fiverm\baselineskip7pt\let\it\fivei\let\bf\fivebf\let\oldstyle\it}
!endverbatim
\exercise How to setup a general \cs{twelvepoint} size-switching macro?
\answer Copy Knuth's \cs{tenpoint} and adjust for the size.
\beginverbatim
\def\twelvepoint{\def\rm{\fam0\twelvenrm}%
  \textfont0=\twelverm\scriptfont0=\ninerm
              \scriptscriptfont0=\sevenrm
  \textfont1=\twelvi \scriptfont1=\ninei
               \scriptscriptfont1=\seveni
  \textfont2=\twelvesy\scriptfont2=\ninesy
              \scriptscriptfont2=\sevensy
  \textfont3=\twelveex\scriptfont3=\tenex
               \scriptscriptfont3=\tenex
  \def\it{\fam\itfam\twelveit}\def\oldstyle
  {\fam1 \twelvei}\textfont\itfam=\twelveit
  \def\sl{\fam\slfam\twelvesl}%
  \textfont\slfam=\twelvesl
  \def\bf{\fam\bffam\twelvebf}%
  \textfont\bffam=\twelvebf
   \scriptfont\bffam=\sevenbf
   \scriptscriptfont\bffam=\fivebf
  \def\tt{\fam\ttfam\twelvett}%
  \textfont\ttfam=\twelvett
  \tt \ttglue=.5em plus.25em minus.15em
  \normalbaselineskip=14pt minus1pt
  \def\MF{{\manual META}\-{\manual FONT}}%fixed
  \let\sc=\tenrm
  \let\big=\fourteenbig
  \setbox\strutbox=\hbox{\vrule 
    height10pt depth4pt width\z@}%
  \normalbaselines\rm}
\def\fourteenbig#1{{\hbox{$\left#1\vbox 
   to12pt{}\right.\n@space$}}}
!endverbatim
Make  sure all the used fonts are available, otherwise
provide scaled versions. See the script for \cs{Large}.

%end answer
\exercise What is the effect of |\bf\it|? And of |\it\bf|?
\answer Once you realize that \cs{bf} and \cs{it} are shortcuts
        to the fonts \cs{tenbf} and \cs{tenit}, actually to the family,
        the answer prompts itself:  the last font, that is italics
        respectively bold face roman.
        One of the features of NFSS is that you will get bold italics
        in both cases, that is these tags commute, or am I mistaken?

\exercise Experiment with the difference between \cs{twelvepoint}
          and the use of \cs{magstep1}.\ftn{Courtesy Nico Temme.}

\bluehead Table of Contents

I must confess that my way of writing has changed.
Now I start keyboarding with a vague idea of the sections and their
structural dependence. 
This style of working badly needs an automatically generated
table of contents, ^{ToC} for short.
The markup to achieve a ToC in the default {\bluetex} reads as follows.
\begincenterverbatim
\input blue.tex \loadtocmacros
\beginscript
<copyproper>
\pasteuptoc
\endscript
!endcenterverbatim
Remark. 
The example titles are interspersed with the sections in the ToC, 
because my purpose is to supply an overview while writing, and 
not for finding the appropriate section to assist the reader.
However, this dynamically generated ToC can be inserted as part of the copy, 
eventually enriched by hand, for the convenience of the reader.

For the \cs{report} format \cs{loadtocmacros} {\em must\/} be omitted.
The necessary macros come already with \cs{report}. 
This ToC is aimed at the reader.

\bluehead Index

The \cs{report} format has been designed to provide also an index on the fly
if one wishes. There is nothing against it to play also with it
in the default format.
\begincenterverbatim
\input blue.tex \loadindexmacros
\beginscript
<copyproper>%marked up with IRs
\sortindex\pasteupindex
\endscript
!endcenterverbatim
\endinput