%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 ||. \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 |\|.} \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 !qquad!hbox!bgroup or!egroup!qquad\{} \end !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\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 or \chapterhead{} \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 or \{} \end !endverbatim || also stored in the token variable |\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