%November 1994, Aug 1995, March 1996
%Paradigm: Headache?
%C.G. van der Laan, cgl@rc.service.rug.nl
\input blue.tex  \loadtocmacros
\tolerance500\hbadness=499\hfuzz=5pt
\parindent=1pc
\everyverbatim{\emc}
 
\bluetitle Paradigms: Headache?
                            
\blueissue \maps{94}2 (revision March\on1996)

\beginscript

\bluehead BLUe's Design II

Hi folks. When using \LaTeX{} 
I was plagued in the past by the little glob of white space
on the first line after a head.
It made me clear that `spaces are harmful,' to paraphrase Dijkstra.
When designing \bluetex{} I had to look at the problem again 
among other things, and to 
\bitem provide a simple suite, with hardly no knowledge of the user
       assumed about parameter separators  
\bitem gobble redundant spaces as much as possible
\bitem allow also processing on the fly of the title
\bitem choose a coding style, and
\bitem choose a `markup language.'
\smallbreak

My starting point was \cs{beginsection}  \TB~\on355.
I chose |head|  as root name conform to TUGboat.

\bluesubhead The revision

is about the superfluousness of the \#
as last element of a parameter specification,
from a functional point of view.

The treatment of \cs{chapterhead} from BLUe's Reports
has been appended of August \on1995. 

A quick and dirty LP functionality to exhibit a ToC
has been added of August \on1995. 
This ToC is not meant to be published but just 
   to assist developing notes, 
   to keep track of the structure, the setup,
which\Dash as reality taught me\Dash
develops too while writing.

Really handy, believe me\winksmiley. 

\bluehead Headers

I will design \cs{beginhead}  and \cs{endhead},
next to the minimal markup variant |\head{ ...}|.\ftn
{The subhead variants are similar but different in detail.
 Especially in undoing  glue when heads follow-up
 each other without intervening text. Beware!}

\bluesubhead Design goals

From a typography point of view I would like to
\bitem discourage to  set the title alone at the end of a page
\bitem typeset (flexible) vertical space (big) before and after (med) the title
\bitem gobble spaces at the beginning of the title
\bitem set the title in bold face (and the current size) unindented
\bitem don't indent the first line of the text after.
\smallbreak

\bluesubhead What are the problems?

The markup language constructs have to be chosen. 
In macro expansion the two-part macro 
\TeX nique should be the basis. In blue's format I adopted 
the pairs |\begin<tag>| and |\end<tag>|.

In order to set the title loose from the context
we have to determine values for the glue,
and be sure that it disappears at the top of a page.
The coding solution below has different values for the 
parameters as supplied in \cs{beginsection}.
From experiments it turned out that the values supplied by Knuth 
don't give nice results with blue.fmt. 
Too much glue was inserted for my taste.

Another problem is to prevent the head title 
to be printed at the bottom of a page on its own. 
The latter is related to the `widow-orphan' phenomenon. 

The coding of the minimal markup variant without parsing
but with processing of the fly of
`the argument' has to be resolved in some elegant way.

The idea of a |\pre<tag>| and |\post<tag>| is  general.
It parameterizes the placement of a document element
within context. Important! Whether you talk about titles,
displays, tables, graphs, or you name it. Perhaps
this should be generalized in something like
|\pasteup<tag>|.
 
\beginverbatim
\def\beginhead{\the\prehead\bgroup\headfont}
\def\endhead{\egroup\the\posthead}
%with auxiliaries
\prehead{\vskip0pt plus2ex
   \penalty-250\vskip0pt plus1ex
   \bigskip\noindent}
\posthead{\medskip\nobreak
   \noindent\ignorewhitespace}%Mod Nov 94
!endverbatim

\bluesubhead Take a deep breath

The minimal markup form, {\em with the same functionality}, reads

\beginverbatim
\def\head{\beginhead\bgroup
   \aftergroup\endhead
   \afterassignment\ignorespaces
   \let\dummy=}
!endverbatim

Explanation.
The replacement text starts \cs{beginhead} and a group.
Immediately after the opening of the group \cs{aftergroup}
takes care that the second part of the two-part macro will be invoked
at the right place. 
The opening brace after the invocation of \cs{head}
is read away by assigning it to \cs{dummy}.
Spaces after the opening brace are ignored, due to
\cs{afterassignment}\cs{ignorespaces}. 
The \TeX nique---moving the group opening---has been 
borrowed from plain's \cs{footnote}, \TB~\on363. 
There it is used at the end of the replacement text of \cs{fo@t}.
\beginquote
What is the difference with the macro with a \# as last element of the 
parameter specification?\ftn
{The \# as last character of the parameter text makes that
 the opening brace and what follows
 is placed after the replacement text of \cs{head}, \TB~\on204.}
\endquote
At first sight it looks identical. However, the difference is twofold.
The situation with the \# at the end of the parameter text differs 
because
\bitem an opening brace after the invocation of \cs{head} is syntactically required 
\bitem no braces are needed for the last argument, because $\{$ is
       a parameter separator.\ftn{The example, \TB~\on204, 
 used the invocation
 |\a3pt{x}|, while without \# as last element of the parameter list
 the markup would have read |\a{3pt}{x}|.} 
\smallbreak

Because of these extra safeguards, 
I stayed with the \# as end of the parameter list,
for building one-part macros on top of two-part macros.
Quite something isn't it?

\bluesubhead Paradigm

We should build upon two-part macros.
In order to add the short variant to {\em similar\/} two-part
macros the following template can be used.

\beginverbatim
\def\<tag>#{\begin<tag>\bgroup
   \aftergroup\end<tag>
   \afterassignment\ignorespaces
   \let\dummy=}
!endverbatim

\bluesubhead Take a deeper breath

When using the above template in practice, 
it occurred to me that \TeX{} could handle that too.
For \cs{head} the desired functionality is that

\beginverbatim 
\onepartmacro{head}
!endverbatim

will build the macro \cs{head} based upon 
the two-part macros \cs{beginhead} and \cs{endhead}.

The naive coding\Dash which does not work, but makes 
the purpose quite clear\Dash reads

\beginverbatim
\def\onepartmacro#1{\def\#1##{\begin#1
   \bgroup\aftergroup\end#1
   \afterassignment\ignorespaces
   \let\dummy=}}
!endverbatim

Several desired functionalities have to be coded 
in \TeX's peculiar way, with as result

\beginverbatim
\def\onepartmacro#1{{
\ea\let\csname begin#1\endcsname=\relax
\ea\let\csname end#1\endcsname=\relax
\toks0={\bgroup\aftergroup}
\toks1={\afterassignment\ignorespaces
        \let\dummy=}
\ea\xdef\csname#1\endcsname##{%
  \csname begin#1\endcsname
  \the\toks0 \csname end#1\endcsname
  \the\toks1 }}}
!endverbatim

Explanation. 
A lot of the trickery about partial expansion, \TB~\on216, has been applied.

First a \cs{csname} is used to compose the names from the root name. 

Second the one-part macro is defined via an \cs{xdef}
with suppression of  the expansion of the 
|\begin<name>|, |\end<name>|, and the other tags.
It is an \cs{xdef}  to keep the auxiliaries used local.
The first is handled via the property that a control sequence
equal to a character, and in general to an unexpandable token, is not expanded.
The second is handled by the property that a \cs{the}
on a token list is a one-step expansion.

\bluesubhead Some remarks

Note that I did not gobble spaces at the end of the title argument. 
In the headtitle they won't harm because
the title is set on a line of its own.\ftn
{In the other heads the space at the end of the argument can be there on purpose.
  Watch out!}

Processing a title on the fly is needed for verbatims
and in general when we don't like the `eyes' of \TeX{}
to set catcodes differently from those the script expects
when digested in the `stomach.' 

\bluesubsubhead The bad news

Minimal markup for \cs{head} and the like can be
felt as an anachronism.
With \AllTeX{} intelligent editors we don't need minimal markup anymore.

\bluesubsubhead Disclaimer

The above template does not work for all two-part macros,
for example not for my btable (or any \cs{halign}).\ftn
{See however, `Paradigms: Two-part macros.'}
 
\bluesubsubhead The good news

Via this mechanism we can abstract
at the {\em user level\/} from token variables and definitions. 
The user can supply the information as if it was a token variable. 
The using of the long form or the minimal form has been reduced
to a matter of taste. And that is a good thing.

\def\head{\beginhead\bgroup
   \aftergroup\endhead
   \let\dummy=}

\bluehead Tests?

This note itself contains examples of use in its original form.

\thisverbatim{\catcode`\|=12 }
\beginverbatim 
\beginhead|Head text 
           in verbatim|\endhead
   Text after\\next line

\head{Head text, with |this| 
      in verbatim}
   Text after\\next line
!endverbatim

 with results
\medskip
\beginlines
\kern-\medskipamount

\beginhead|Head text in verbatim|\endhead
%\head{{\tt Head text in verbatim}}
   Text after\\next line

\head{Head text, with |this| in verbatim}
   Text after\\next line
\medskip
\endlines
\medbreak
Run it,\ftn{blue.tex is available form the CTAN,
   as is the accompanying article BLUe's Format.}
and have fun. All the best.

\bluehead Note added in proof

In order to allow blank lines after the heading in the script, 
I replaced \cs{ignorespaces} in \cs{endhead} by  
\cs{ignorewhitespace}.\ftn{Due to Phil Taylor. 
  TUG's \cs{ignorespacesandpars} would probably do too.}

A blank line after a heading is natural for a text without explicit markup.
Knuth started from natural markup and stayed close to that, IMHO. 
His markup tags to format the chapter (titles and contents) in \TB{}
file are

\beginverbatim
\beginchapter
\endchapter
!endverbatim

Imagine ASCII text with visual layout, and in order to markup
the title {\em and text\/} insert the above commands, with the natural
blank line already there to end the arguments of \cs{beginchapter}.
Knuth's \cs{beginchapter} not only takes care of the title but also
handles the chapter contents {\em on the fly\/} until \cs{endchapter}
is encountered. 
Really much different from \LaTeX's approach, to name but
one general set of markup tags.

\bluesubhead Knuth and natural markup

Imagine that the ASCII text of a section reads
\beginverbatim
Section 1. Title

Now starts the section text 
proper...
And this is the last line of it.
!endverbatim

What is the simplest and most natural markup for this?
First the requirements
\bitem section should be flexible towards language variation
\bitem title should be processed on the fly.
\smallbreak

A solution is the following extension heavily inspired by
\cs{beginchapter} of manmac.

\beginverbatim
\def\beginsection#1 #2#3. {\bgroup
   \def\par{\egroup\endhead}%
   \beginhead#1 #2#3. }
\posthead{\nobreak\medskip
   \noindent\ignorewhitespace}
%
\let\endsection\relax%or forget about it
%
\def\ignorewhitespace{\begingroup
%Due to Phil Taylor EuroTeX 94
\catcode`\ =9
\catcode`\^^I=9
\catcode`\^^L=9
\catcode`\^^M=9
\futurelet\dummy\endgroup}
!endverbatim

The marked up script is obtained by only inserting \cs{beginsection}!

\beginverbatim
\beginsection Section 1. Title

Now starts the section text 
proper...
And this is the last line of it.
!endverbatim

The beauty of the above approach, Knuth's IMHO, is that the total section 
is handled, the title as well as the contents part, with the title
proper part processed on the fly. 
Moreover, it is as close to natural markup as I can think of.
(trivial) Language problems are absent. 
One can abstract from `Section' via a toks variable \cs{sectionname}.
Automatic numbering can be inserted too, but the question is
whether it is really handy, especially in view of subsections and the
like.

\bluehead Copied from BLUe's Report

In BLUe's Report I have dealt with more complicate header matters, 
which show up when we like to reuse the title for inclusion in
the ToC, ToE and ilks. It turns out that `\cs{bluechapter}'
is much more complicated than `\cs{bluehead}.' 
Below the storing of titles and their reuse is dealt with among other things.
Because of storing\Dash which fixes the catcodes\Dash
the titles are not processed on the fly.

\bluesubhead Chapter head matters

The required functionalities\Dash the specs so to say\Dash are to
\bitem start a new page
\bitem store the title for reuse (running head, table of contents)
\bitem maintain and store the chapter counter (for use with the exercises,
        table of contents, and the like)
\bitem write the title and title counter value to the contents file
\bitem typeset the title on a new page with some white space after
\bitem reset counters which start anew per chapter (headings, exercise number,
       and the like)
\bitem provide the right \cs{headline} and \cs{footline} with the title,
       chapter title, and page number
\bitem suppress the headline on the first page of a chapter (or supply for
       an otherwise special headline)
\bitem process the title on the fily to allow for example verbatim
\bitem condition the writing of the title and title counter value 
       to the examples file.
\smallbreak

Quite something, isn't? 
That is why title matters are not trivial.
The conditioning of writing the title to the examples file is there,
because we don't like the title etc. to appear in that file if the chapter
lacks examples.

\beginverbatim
\def\beginchapterhead{\the\prechapterhead
  \storechaptertitle}
%
\def\storechaptertitle#1\endchapterhead{%
   \global\chaptertitle={#1}\endchapterhead}
%
\def\endchapterhead{\centerline{\chapterfont
   \the\chapternumbering\the\chaptertitle}
   \the\postchapterhead\ignorewhitespace}
!endverbatim

This approach looks promising.
What has to be done before is the concern of \cs{prechapterhead}.
\cs{storechaptertitle} does what its name suggests.
The formatting of the number of the chapter is the concern 
of \cs{chapternumbering}.
\cs{postchapterhead} takes care of leftovers.
Default \cs{chapternumbering} is empty, that is, no number will be typeset.

Undoubtedly, the careful reader would object that the title is stored
and that the catcodes are set  before processing.
That is right, of course, but via \cs{everychapterhead}\Dash in 
\cs{prechapterhead}\Dash 
we can guarantee that symbols will have the right catcodes.
\cs{storechaptertitle} is there to allow the short variant
|\chapterhead{...}|.
The combination of storing and in-line verbatim does not work. Beware.\ftn
{For me this does not hinder because I don't like these kinds of font changes
 in a chapter header.}

\beginverbatim
\prechapterhead{\newpage\null\vskip4pc
   \bgroup\catcode`\^=7 
   \the\everychapterhead\the\thischapterhead 
   \global\advance\chaptercnt1 }
%
\postchapterhead{\egroup
   \headcnt0 \exercisecnt0 \examplecnt0 
   \write\toc{\nx\separator
      {\alfanum\the\chaptercnt}
      {\the\chaptertitle}}
   %suppress headline first page chapter
   \headline{\global\headline
    {\hbox to\pagewd
     {\sl\the\chaptertitle\hfill
                    \the\title}}}%
   \footline{\hbox to\pagewd{\small
     \rlap{Draft \today}\hfill\dash
    {\oldstyle\the\pagenumber}\dash
     \hfill\llap{\copyright
                 \the\crowner}}}%
%Example is redefined here such that on 
%first use if ever in the chapter, it 
%redefines itself into the regular macro, 
%while writing the chapter titles to the 
%table-of-examples, ToE, file.
%In this way chapter titles of chapters 
%without examples will not be written to
%the ToE. 
   \def\example{\write\toe{\nx\separator
       {\alfanum\the\chaptercnt}
       {\the\chaptertitle}}
      \let\example\regularexample
      \example}
   \thischapterhead{}\vskip3pc}
!endverbatim

The material is enclosed within a group to keep the effect
of \cs{thischapter} local.

\cs{example} is defined such that only when it is used
the title and number of the chapter will be written to the file
associated with \cs{toe}. \cs{regularexample} writes the example title
and number to the file associated with \cs{toe}.

Intriguing is \cs{alfanum}. The purpose is to control whether a number
or a letter should appear. This is particularly useful with appendices.
\beginverbatim
\def\setupappendices{\thischapterhead=
   {\chaptercnt64 \gdef\alfanum{\char}%
    \global\chapternumbering=
    {\alfanum\the\chaptercnt: }}}
!endverbatim

And what about the one-part macro on top?
The above was already complicated. 
What is the problem for a one-part macro?
For most of the cases we can do with a simple variant. 
However, when we like to process math, especially the circumflex,
as part of the title more work has to be done. The mechanism has been 
explained in `Paradigm: Two-part macros.'

\beginverbatim
\def\chapterhead{\bgroup
   \def\storechaptertitle##1{\egroup
     \global\chaptertitle{##1}%
     \endchapterhead}\beginchapterhead}
!endverbatim

As a tribute to manmac I also defined the following limited variant.\ftn
{The circumflex in math in the title will hiccup. Most of the time we
 don't need that.}

\beginverbatim
\def\bluechapter#1\par{\beginchapterhead
   #1\unskip\endchapterhead}
!endverbatim

A trivial user interface on top which counteracts the curly braces mania
at the expense of processing on the fly.\ftn
{What does on-the-fly mean anyway, when we have to store the title for multiple use?
 The answer is that we would like to allow for math too. No verbatims however.}

\bluehead A little LP functionality

Of late with notes I needed to generate automatically a small rudimentary
ToC to assist my writing and developing notes. Just quick and dirty.
For that purpose I provided the following for the |\blue(sub(sub))head|-s.\ftn
{Be aware that these head titles are not processed on the fly.
 In March \on1996 I replaced writing to a file by maintaing the toc in a toks variable,
 because in general it is not a mouth-only process the writing can go astray.
 It did with |$\longrightarrow$|. Actually, for this toc assitant I did not need 
 the output functionality of adding page numbers.}

\beginverbatim
\newtoks\tocvar
\let\bh\bluehead
\long\def\bluehead#1\par{\bh#1\par
\tocvar\ea{\the\tocvar\par#1}}
\let\bsh\bluesubhead
\long\def\bluesubhead#1\par{\bsh#1\par
\tocvar\ea{\the\tocvar\par\quad#1}}
\let\bssh\bluesubsubhead
\long\def\bluesubsubhead#1\par{\bssh#1\par
\tocvar\ea{\the\tocvar\par\qquad#1}}
\let\be\blueexample
\long\def\blueexample#1\par{\be#1\par
\tocvar\ea{\the\tocvar\par\qquad ex: #1}}
!endverbatim

For pasting up the ToC I supplied.
\beginverbatim
\long\def\pasteuptoc{\newcol
   \bluehead Contents\par
   \the\tocvar
   \let\makesignature\relax}
!endverbatim

Finally, I merged the above into BLUe's format system. 
The toks storage allocation for \cs{tocvar}
and \cs{loadtocmacros} in blue.tex, and 
the rest in tools.dat.

The user can supply 
\cs{loadtocmacros} at the beginning after |\input blue.tex|, and
\cs{pasteuptoc} just before \cs{endscript}.

In this way these macros don't conflict, just an extra
to support your notes with a ToC at the end, to maintain 
the overview.\ftn{Note that \cs{report} already provides for a ToC.}

\bluehead Acknowledgements

Phil Taylor is kindly acknowledged for his \cs{ignorewhitespace}
as generalization of \cs{ignorespaces}, and his suggestion to assign 
\cs{relax} to tokens to inhibit expansion instead of a number.
The latter is done on \TB~\on216.

Have fun, and all the best.
\makesignature
\pasteuptoc
\endscript