%November 1994,Summer 1995, Paradigma: Two part macros
%C.G. van der laan, [email protected]
\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

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.