path: root/info/laan/paradigm/paradigm.two

%November 1994,Summer 1995, Paradigma: Two part macros
%C.G. van der laan, cgl@rc.service.rig.nl
\input blue.tex \loadtocmacros 
\outer\def\endmathdemo{\crcr\egroup$$}
\tolerance500\hbadness=499\hfuzz=10pt
\parindent=1pc
\everyverbatim{\emc}

\bluetitle Paradigms: Two-part macros

\blueissue\maps{95}1

\beginscript

\bluehead BLUe's Design III

Hi folks. When attending Amy's class in \on1990, 
I was much surprised about
the two-part macro. In Algol, FORTRAN, PASCAL and ADA, 
I had not heard of the concept, let alone I was familiar with it.

In \bluetex{} they are at the heart of the syntax for the markup language.
To speak with Jackowski `I use them all the time.'

\bluehead One-part vs.\ two-parts

One-part macros are explained in Chapter \on20 of \TB.
They are used as a shortcut for the replacement text
parameterized by at most nine arguments.

A two-part macro is different. The first part sets up
the `environment' followed by  script elements and ended
by the second part, to finish up the environment.
\LaTeX{} emphasizes the environment concept in for example
\beginverbatim
\begin{abstract}...\end{abstract}
\begin{center}...\end{center}
\begin{itemize}...\end{itemize}
\begin{picture}...\end{picture}
\begin{quote}...\end{quote}
\begin{tabular}...\end{tabular}
\begin{thebibliography}...
          \end{thebibliography}
\begin{verbatim}...\end{verbatim}
%etc.
!endverbatim 

\bluehead Why?

The need for bothering about two-part macros is that the
enclosed script elements are processed on the fly, meaning with
the right catcodes.

To digress a little on the above the following hypothetical example.
Suppose we have
\beginverbatim
{\catcode`*=13
 \gdef\begindemo{\begingroup
   \catcode`*=13 \def*{MUL}}
 \gdef\demo#1{\catcode`*=13 \def*{MUL}#1}
}\let\enddemo\endgroup
!endverbatim
then the result of
\beginverbatim
\begindemo*\enddemo 
%and
\demo*
!endverbatim
is different. The first yields MUL and the latter *.\ftn{A robustness aspect is to
   use \cs{begingroup} and \cs{endgroup} instead of \cs{bgroup} and \cs{egroup},
   to facilitate the location of (user) unmatched braces in between.}

Explanation.
In the two-part case the * is seen after the catcode has changed.
while in the latter the * is seen, and the catcode {\it fixed}, before it
is made active.

\bluehead Two-part macros

In Chapter \on20 of \TB{} there is no treatment
of two-part macros, nor is there an entry for it in the index, alas.
Exercise \on5.\on7 deals with named blocks and 
checking of them. 
The latter is used in \LaTeX{}  to make sure 
that the right environment closing tag is used in the markup.
In Appendix~E, where example formats (o.a.\ manmac) are explained, 
two-part macros are abundant, for example
\beginverbatim
\beginchapter...\endchapter 
\beginlines...\endlines
\begindisplay...\enddisplay
\begintt...\endtt
\begimathdemo...\endmathdemo
\beginchart...\endchart
\beginsyntax...\endsyntax
\begindoublecolumns...\enddoublecolumns
\exercise...\answer...\par
!endverbatim
Furthermore, of late two questions were posed on TeX-nl, which exposed
the unfamiliarity with two-part macros. All this was enough for me to
spend a paradigm column on two-part macros.\ftn{Note that \cs{beginchapter}'s
   title is not processed on the fly. In the `Paradigm: Headache?' I have shown
   how the title and the contents of the chapter can be processed on the
   fly.}

\blueexample \cs{beginlines}\dots\cs{endlines}

The functionality is that the script in between is processed
line-by-line and the result is preceded and followed by an \cs{hrule}.
\beginverbatim
\def\beginlines{\par\begingroup\nobreak
   \medskip\parindent0pt\hrule\kern1pt
   \nobreak\obeylines\everypar{\strut}}
\def\endlines{\kern1pt\hrule\endgroup
   \medbreak\noindent}
!endverbatim
In the \TeX book script this is combined with in-line
verbatim.\ftn{To set text verbatim. By the way, this is another approach
   to `verbatims with an escape character.'}

Explanation.
The replacement text of \cs{beginlines}
is processed, followed by the formatting on-the-fly of the inserted material 
(after \cs{beginlines}) up to \cs{endlines}. 
The replacement text of the latter finishes it up.  

Unwanted breaks are avoided. 
The \cs{hrule} is set in the first part and in the
second part next to opening and closing of the group.
The in between script is processed with \cs{obeylines} on.

\blueexample \cs{begindisplay}\dots\cs{enddisplay}

The functionality is that the script in between is processed
as a non-centered display, indented by \cs{displayindent}, 
next to the value of \cs{parindent} from the template.
Pruned from non-essential issues for the two-part macro idea,
the macros read as follows.
\beginverbatim
\def\begindisplay{$$\the\thisdisplay\halign
   \bgroup\indent##\hfil&&\qquad##\hfil\cr}
\def\enddisplay{\crcr\egroup$$}
!endverbatim

Explanation.
The replacement text of \cs{begindisplay}
is processed, followed by the formatting on-the-fly of the inserted material 
(after \cs{begindisplay}) up to \cs{enddisplay}. 
The replacement text of the latter finishes it up.  

By the way, note that the user is not bothered by the details
of the template of the \cs{halign};
it is already there.\ftn{In my \cs{btable} macro, I allowed the possibility
   for a user to supply his own template, because I stored the
   template in a token variable.}

\bluesubhead Alignment display

\$\$ followed by \cs{halign} is special, an exception. 
It starts the so-called alignment display, meaning that
each hbox of the \cs{halign} is added to the main vertical list
indented at the left by \cs{displayindent}.
It is {\it not a math display}.
\cs{the}\cs{thisdisplay} allows to insert assignments.

\bluesubhead And what about a one-part on top?

This is not possible via my method as explained in
`Paradigms: Head\-ache?', because each table entry
must have balanced braces. Suppose we have

\beginverbatim
\def\display#{\begindisplay\bgroup
   \aftergroup\enddisplay
   \let\dummy=}
!endverbatim

then the \cs{bgroup} after \cs{begindisplay} is `unbalanced' in the first
column, except when it is about one entry only.

\beginverbatim
\display{a}  %works
\display{a&b}%doesn't work
!endverbatim

\bluesubsubhead I let it go

Because I could not provide a nice solution I let it go. 
What I tried is out of balance with just using the two-part macros.
The best I could get at, when we allow in-line verbatim, needs the
following input.

\thisverbatim{\catcode`\!=12 \catcode`\*=0 }
\beginverbatim
\thisdisplay{\catcode`\!=0 \catcode`\\=12 }
\display{|\a|&b!cr e&f}
*endverbatim

\bluesubsubhead Conclusion

When tables are involved my  method of building  one-part 
macros on top of two-part macros is not suited.\ftn
{If one prefers a simple, but {\em restricted\/} one-part macro provide
 |\def| |\display#1{| \cs{begindisplay} |#1| |\enddisplay}|.}
On the other hand for all those cases where the method works I have provided also
a macro such that \TeX{} can add the one-part automatically given the |<root>|.

\bluesubhead Manmac's two-part macros 
 
These are treated in \TB~\on421. 
Note that there the |\catcode`\^^M| annihilates the effect of \cs{obeylines}.
The \cs{obeylines} was introduced only to allow for an optional argument. 
Because of my \cs{thisdisplay} toks variable, the \cs{obeylines}
and its annihilator are no longer needed. 
Knuth's coding has been simplified, at the expense of introducing
a token variable \cs{thisdisplay}.\ftn
{Optional arguments\Dash well, more generally `Parame\-te\-riz\-ation'\Dash 
 will be subject of the next paradigm column.}
  
\bluehead From the \TeX-nl list

Andrea de Leeuw van Weenen and Ton Biegstraaten posed the following problems.
\bitem  let characters print other characters
\bitem  let |_| in math denote an underscore and not a subscript.
\smallbreak

Although it turned out that my suggestions are not the \on100\% required ones,
I'll expose them here nonetheless, because they illustrate the use of two-part 
macros.

\bluesubhead Andrea's problem

Let us suppose that the problem is to let B typeset 1, on demand.
A solution reads.

\beginverbatim
\def\beginIT{\begingroup\catcode`\B=13 \ITstart}
{\catcode`\B=13 
 \gdef\ITstart{\def B{\char'61}}}
\let\endIT\endgroup
%with use
ABC\quad
\beginIT ABC\endIT\quad
ABC
!endverbatim

\def\beginIT{\begingroup\catcode`\B=13 \ITstart}
{\catcode`\B=13 
 \gdef\ITstart{\def B{\char'61}}}
\let\endIT\endgroup

The result reads\quad
ABC\quad
\beginIT ABC\endIT\quad
ABC.

The problem which remained is that Andrea needs 
simultaneously macros with those letters like B in their name.
She added the problem to her list of 
`Impossible with \TeX{} problems.\ftn
{I'm curious to see that list in MAPS some day.}'
   
\bluesubhead Ton's problem

The restriction, which made that my solution was not appropriate,
is that it should be possible to use the solution as argument
of one-part macros, and that to unlimited depth.\ftn
{Courtesy Piet van Oostrum.}
In my approach all involved one-part macros had to be rewritten
into two-part ones.
However, if people would start to think in two-part macros
(nearly) all would have been fine.

\beginverbatim
\def\beginusn{\hbox\bgroup\catcode`\_=13
   \startusn}
{\catcode`\_=13\gdef\startusn{\def_{\_}}}
\def\endusn{\egroup}
%with use
$a_b\quad \beginusn a_b\endusn\quad a_b$
!endverbatim

\def\beginusn{\hbox\bgroup\catcode`\_=13\startusn}
{\catcode`\_=13\gdef\startusn{\def_{\_}}}
\def\endusn{\egroup}

\noindent and result\quad
$a_b\quad \beginusn a_b\endusn\quad a_b$.

On top of the above two-part macros we can add  one-part macros
{\it wih the same functionality}, as explained in the `Paradigm: Headache?'
 
The one-part macros read

\beginverbatim
\def\IT{\beginIT\bgroup
   \aftergroup\endIT
   \let\dummy=}
%
\def\usn{\beginusn\bgroup
   \aftergroup\endusn
   \let\dummy=}
!endverbatim

\def\IT{\beginIT\bgroup
   \aftergroup\endIT
   \let\dummy=}
%
\def\usn{\beginusn\bgroup
   \aftergroup\endusn
   \let\dummy=}
As expected |ABC\quad\IT{ABC}\quad ABC|\\
yields
\quad ABC\quad\IT{ABC}\quad ABC, and
\par
|$a_b\quad\usn{a_b}\quad a_b$|\\
yields
\quad $a_b\quad\usn{a_b}\quad a_b$.

Note that I omitted here the \# as last element of the parameter list, 
neglecting some built-in security checks.\ftn
{In the case of the \# end separator the text after the macro invocation 
 must syntactically begin with an opening brace.
 When the \# separator is omitted, anything can follow |\<tag>|.}

\bluehead Eqalign as two-part macro

As an example of how to cast a one-part macro into two parts,
and a one-part macro\ftn{Not more limited than the one available.}
on top, let us rewrite \cs{eqalign}, \TB~\on362. 
The extra functionality of this approach is 
that the two-part variant can be used in those cases where 
the argument needs to be processed on the fly. 

\beginverbatim
\def\begineqalign{\,\vcenter\bgroup
   \the\thiseqalign\openup1\jot\m@th
   \starteqalign}
\def\starteqalign{\ialign\bgroup
   \strut\hfil$\displaystyle{##}$&&
   $\displaystyle{{}##}$\hfil\crcr}
\def\endeqalign{\crcr\egroup\egroup}
%with the one-part
\def\eqalign#1{\begineqalign
   #1\endeqalign}
!endverbatim

I don't have a concrete example for the need for modifying 
\cs{eqalign} towards processing on the fly. However, it illustrates how
to rewrite a one-part macro into two-parts as basis. 

\bluehead Looking back

I like the consistent markup via

\thisverbatim{\emc}
\beginverbatim
\begin<tag>
<copy>!qquad!hbox!bgroup or!egroup!qquad\<tag>{<copy>}
\end<tag>
!endverbatim

The right-hand variant is suited for the markup of headings, for example.
It has been adopted in \bluetex, as basic syntax, for the markup language.

As an extra user-interface I have added in BLUe's format system as a tribute to manmac
tags of the form

\beginverbatim
\blue<tag><copy>\par%or blank line
!endverbatim

They have lost the processing on the fly behaviour but they are suited for minimal
markup, reducing the number of curly braces.

\bluehead Multiple use of copy

Sometimes we need to process the copy\Dash or should we talk about data then?\Dash 
more than once. 
An example is the data for a crossword, where I used the data for typesetting 
the puzzle\Dash the data reflect the structure\Dash 
and the solution. 
See `Typesetting crosswords via \TeX, revisited,' \maps{92}2.

The basic idea is to store the data with the right catcodes.\ftn
{Perhaps the most trivial approach is to insert the data each time we need it.
 I consider that inelegant and also error-prone. The given macro is a
 beautiful example, if I may say so, of what Victor Eijkhout and 
 David Salomon call two-step macros (see later), 
 while at the user level the macro can be used
 as if it is a two-part macro, with the nice opening and closing tags.}

\beginverbatim
\def\bdata{\begingroup
   \obeylines\obeyspaces\store}
\def\store#1\edata{\endgroup
   \def\storeddata{#1}}
!endverbatim 

Explanation.
The data, in natural markup line-by-line, 
can be supplied between \cs{bdata} and \cs{edata}. The \cs{edata}
is a parameter separator and not the invocation of the closing part 
of a two-part macro, although it looks the same.
What happens is that \cs{bdata} sets up the environment, especially provides
the right catcodes. \cs{store} ends the environment (scope) and 
stores the data, with the wanted catcodes, as replacement text of 
\cs{storeddata}.

In order to appreciate the subtleness of the above coding 
the following digressions. 

\bluesubhead Two-part macros and storing on the fly

This is inhibited by the following\ftn
{Courtesy  Victor Eijkhout in `\TeX{} by Topic,' section \on10.\on3 group delimiters. 
 Awareness of these restrictions is indispensable for writing two-part macros. 
 I omitted the use of \cs{setbox}, because once set in a box one can't do much with 
 the data anymore.} 
\bitem the {\it opening and closing brace\/} of the 
       replacement text of a \cs{def}  must be explicit
\bitem the right-hand side of a token list assignment must be explicit.
\smallbreak

The following innocent coding is therefore incorrect.\ftn
{The use of explicit braces is incorrect as well.}

\beginverbatim
\def\bdata{\begingroup
   \obeylines\obeyspaces
   \gdef\storeddata\bgroup}
\def\edata{\egroup\endgroup}
!endverbatim

Possible alternatives to my coding above are

\beginverbatim
\def\data{\obeylines\obeyspaces
  \gdef\storeddata}
%with use
\begingroup
\data{ab c
      e fg}
\endgroup
%
%and via the use of a toks variable
%
\newtoks\storeddata
\def\data{\obeylines\obeyspaces
  \global\storeddata}
%with use
\begingroup
\data{ab c
      e fg}
\endgroup
!endverbatim 

Nice aspects of the above approaches are
\bitem at the outer level I abstracted from storing in a def or a token 
       variable, and 
\bitem the symmetry.
\smallbreak

Definitely not nice aspects are 
\bitem it looks as if the data are stored in \cs{data}, and
\bitem the \cs{begingroup} and \cs{endgroup} at the user level.
\smallbreak

\bluesubhead A one-part on top

My scheme does not work for this case. Some puzzling yielded
as one-part \cs{data} on top of \cs{bdata}, 
with \cs{edata} eliminated.\ftn
{Note that in-line verbatim as part of the data goes wrong in the sense of unexpected results.}

\beginverbatim
\def\data{\begingroup
    \def\store##1{\endgroup
       \gdef\storeddata{##1}\endgroup}
    \bdata}
%With use
\data{ab c
      d ef}
!endverbatim

Explanation.
\cs{data} starts a group and (re)defines \cs{store}.
The invocation of \cs{bdata} set the catcodes\Dash via \cs{obeylines} and
\cs{obeyspaces}\Dash and invokes \cs{store}.
The argument to the latter macro is stored in
\cs{storeddata} with the right catcodes. 
\cs{store} also ends the groups.\ftn
{The group opening in \cs{bdata} is not needed here, but
 within the context of the two-part macro next to the one part, it is needed.}  

\bluesubhead Chapterhead

For \bluetex{} I designed \cs{report}. A report takes chapter titles.
The problem is how to write macros consistent with the philosophy of starting from 
two-part macros and building a one-part on top, {\it with\/} the chapter
title also stored for use in the running headline, for example.

In an abstract sense this is equivalent to the \cs{bdata} \cs{edata}, \cs{data} suite. 
It is even simpler, because I just have to store the title and allow the following use.

\beginverbatim
\beginchapterhead 
<titlehead>        or    \chapterhead{<titlehead>}
\endchapterhead
!endverbatim

The  result must be such that the chapter title will be typeset appropriately within the context, 
as prescribed by the token variables  \cs{prechapterhead} and \cs{postchapterhead}, and 
that the title will be stored in the token variable \cs{chaptername}.

\bluesubsubhead Coding the two-part macros 

The coding of the two-part macros read as follows.

\beginverbatim
\def\beginchapterhead{\the\prechapterhead
   \storechaptername}
\def\storechaptername#1\endchapterhead{%
   \chaptername={#1}\endchapterhead}
\def\endchapterhead{{\chpfont
   \the\chaptername}\the\postchapterhead}
!endverbatim

\bluesubsubhead Coding the one-part macro on top 

The one-part macro on top reads as follows.

\beginverbatim
\def\chapterhead{\bgroup
   \def\storechaptername##1{\egroup
     \global\chaptername={##1}%
     \endchapterhead}
   \beginchapterhead}
!endverbatim

The head-suite of macros also need processing and storing if not for writing to a ToC file. 
The use of the token variable \cs{prechapterhead} provided the hook to change 
the catcode of the circumflex\Dash 
which in \bluetex{} is default active because of preparing Index Reminders\Dash 
into \on7 and allow processing math as part of the title. 

\bluesubsubhead What have we gained?

We can use now the title with different fonts, as title and in the running head. 
Moreover, we can use the \cs{beginchapterhead}, \cs{endchapterhead} pair 
to enclose the title, or let it look as an  assignation to |\chapterhead|.
Looking back a paradigm  emerged for the following.

\beginverbatim
\begin<tag>
<copy>            or    \<tag>{<copy>}
\end<tag>
!endverbatim

|<copy>| also stored in the token variable |\<tag>name|.
Useful.

\bluesubhead Multiple use with different catcodes

Like Knuth we are at loss, unless we make use of a file.
It occurs in manmac's math demos, for example
\beginmathdemo%TeXbook 128
   \it Input&\it Output\cr
   \noalign{\vskip2pt}
   |$x^2$|&x^2\cr
\endmathdemo
needs markup with repetition of the data\ftn
{Borrowed from \TB{} script. In \bluetex{} I added \cs{crcr}
 to \cs{endmathdemo}, for consistency with \cs{halign} use.}

\thisverbatim{\catcode`\|=12 \unmc}
\beginverbatim
\beginmathdemo
   \it Input&\it Output\cr
   \noalign{\vskip2pt}
   |$x^2$|%<---
   &x^2   %<---
\endmathdemo
!endverbatim
 
Subtle, very subtle. One thing is crystal clear, however.
\beginquote
Because of the above varieties (and pitfalls?),\\ 
a discipline of \TeX{} coding is needed.
\endquote

\bluehead Epilogue

Eijkhout in `\TeX{} by Topic' and Salomon in `Insights and Hindsights'
treat {\it two-step\/} macros, not {\it two-part\/} macros.\ftn
{Apparently they did not inspect manmac in detail. 
 In Eijkhout's book look at section \on11.\on9.\on4, the macro \cs{PickToEol}. 
 In Salomon's courseware look at section \on5.\on19, the macro \cs{elp}.} 
One macro will set up conditions and a second  will do the work.
The difference with two-part macros is that the `work macro' also terminates the conditions, 
while in two-part macros the second part has only the functionality to terminate. 
Probably other macros are involved to do the work.
A beautiful example from manmac is the non-centered display macro with the following tags.

\beginverbatim
\begindisplay %to set up conditions
\startdisplay %to do the work
\enddisplay   %to finish up
!endverbatim

As known, I prefer\Dash like Knuth\Dash the separation of concerns principle, and 
like opening and closing tags. 
But, \dots I prefer {\em implicit\/} closing tags, in short minimal markup.

To my knowledge it is not possible to build gracefully, 
and with the {\it same functionality}, a one-part {\em table\/}  macro 
on top of its constituent two-parts, in full generality.

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