diff options
Diffstat (limited to 'info/laan/paradigm/paradigm.two')
-rw-r--r-- | info/laan/paradigm/paradigm.two | 622 |
1 files changed, 622 insertions, 0 deletions
diff --git a/info/laan/paradigm/paradigm.two b/info/laan/paradigm/paradigm.two new file mode 100644 index 0000000000..819514c0b8 --- /dev/null +++ b/info/laan/paradigm/paradigm.two @@ -0,0 +1,622 @@ +%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
\ No newline at end of file |