summaryrefslogtreecommitdiff
path: root/info/laan/paradigm/paradigm.two
blob: 819514c0b87c58ee2fa2089c82f11d617f41b932 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
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