summaryrefslogtreecommitdiff
path: root/info/laan/paradigm/paradigm.two
diff options
context:
space:
mode:
Diffstat (limited to 'info/laan/paradigm/paradigm.two')
-rw-r--r--info/laan/paradigm/paradigm.two622
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