%November 1994, March 1996.
%Paradigm: Parameterization---Options
%C.G. van der laan, cgl@rc.service.rug.nl
\input blue.tex \loadtocmacros
\tolerance500\hbadness=499\hfuzz=9pt
\parindent=1pc
\everyverbatim{\emc}
\bluetitle Paradigms: Parameterization I
\bluesubtitle Options
\blueissue \maps{95}1
\beginscript
\bluehead BLUe's Design IV
Hi folks. Much parameterization in \TeX{} has already been
taken care of via the various modes of \TeX, that is by the states
script elements can be processed in.
How ingenious and handy that may be, it is not sufficient.
Knuth also provided switching commands for fonts, formats and
language.\ftn{For example \cs{eightpoint}, \cs{report} (well in
\bluetex),
and \cs{language1}. Similar to the font switching macros I used
\cs{english}, \cs{dutch} and the like, to activate all
language dependent parameters for typesetting bridge
with the right words. Early \LaTeX{} had several
words `hardwired' in the code in English.
The latter was the reason for Johannes Braams to give birth
to Babel, to parameterize and concentrate language specific
issues, and to allow easy switching
from one language to another.}
Then there are the various parameters\Dash integer, dimen,
glue, muglue\Dash as listed in \TB{} \on272\dash\on274.
Markup tags can be parameterized via (at most \on9) arguments.
However, there exist also for this purpose (global) token variables\Dash
the |\every<tag>|s\Dash with \cs{output} and \cs{errhelp} as special cases.
To remind the reader of Knuth's \cs{every}s, I have
enumerated them below.
\beginverbatim
\everypar
\everymath, and \everydisplay
\everyhbox, and \everyvbox
\everyjob
\everycr
!endverbatim
For using them, it is important to know where the token variables are
precisely inserted.\ftn{For example, in a setbox the right-hand
side of \cs{afterassignment}
is inserted after the opening brace of the box and
followed by the tokens of |\everyh/vbox|.}
For my taste Knuth's |\every<tag>|s
have not been appreciated as they should have been, the more so
when extended by the analogons |\this<tag>|s.\ftn{This functionality of |\this<tag>|
can be obtained via the use of |\every<tag>| within a group. However, readability
of the marked up script is served by the use of |\this<tag>|-s.}
This in contrast with the abundant use of arguments,
especially the so-called optional arguments.
\bluesubhead Why?
The purpose of this note is to show that
optional arguments have led to cumbersome \TeX{} coding, while
the same functionality can be attained more easily via the use of
|\this<tag>|s.
In general one can devote a monograph to markup language
parameterization, I guess.
\bluehead Examples of use of \cs{every}s
I inspected \TB{} for examples of use by Knuth himself.
\bluesubhead \cs{everypar}
An example of use is given in Appendix~D \on381, about
verbatim listings with line numbers. In \bluetex{} I enriched this
approach by allowing selective line numbering.
I mean by the latter that I can number parts,
starting with any suitable number.
This is handy when macro sets are accompanied by a table of contents
(as should always be the case), which contains references to
the line numbers of the macro set.
From \bluetex{} the following.
\thisverbatim{\catcode`\*=0
\catcode`\!=12 }
\beginverbatim
\def\setupverbatim{\makeactive\`%
\let\!=!\makeescape\!%Knuth&Levy
\def\par{\leavevmode\endgraf}%381
\obeylines \uncatcodespecials
\obeyspaces}
%
\def\numvrb{\vrblin0
\everypar{\advance\vrblin1
\llap{\sevenrm\the\vrblin\quad}}}
%
\def\nonum{\everypar={}}
*endverbatim
Note that the line numbers can be adjusted via modifying the counter \cs{vrblin}.
Another example is provided on \on393, in Paragraph maneuvers.
It is about automatically inserting \cs{hangindent} and \cs{hangafter}.
In manmac it is used in
\bitem \cs{endchapter}, as |\everypar{\sl}|, to set the quotations slanted.
\bitem \cs{beginlines}, as |\everypar{\strut}|, to insert a strut.
\smallbreak
\bluesubsubhead A pitfall
What is the unexpected result of
\beginverbatim
\par%or other ending of a paragraph
{\bf New paragraph} blah blah
!endverbatim
with |\everypar{\hang}| active\ftn{Courtesy Alan Reese}?
And why?\ftn{Courtesy Jeremy Henty.}
Note that \cs{bf} is only there to make the pitfall look realistic.
Answer.
Without braces the text comes out as a block. With the braces at the
beginning there is no effect of the automatically inserted \cs{hang}.
The explanantion reads as follows.
When processing ordinary text, \TeX{} does not enter horizontal mode
until it encounters a letter. In the troublesome paragraph the first
letter is inside a group. When the group ends all local assignments
are undone, and the effect of the \cs{hang} instruction\Dash
the contents of \cs{everypar} is inserted within the group\Dash
is forgotten.
A solution is to precede the group by \cs{leavevmode},
because the \cs{everypar} will be executed before the group then.
\bluesubhead \cs{everydisplay}
This is used in the solution of exercise \on19.\on4 to obtain non-centered displays.
\beginverbatim
\def\leftdisplay#1$${\leftline
{\indent$\displaystyle{#1}$}$$}
\everydisplay{\leftdisplay}
!endverbatim
This is refined in Appendix~D \on376, to allow for equation numbers as well.
In `Math into BLUes' I have worked on the Appendix~D version, and also indicated how
a single formula can be non-centered.
This is also included in \bluetex.
\bluesubhead \cs{everyjob}
The example is exercise \on24.\on5.
In Salomon's courseware an example is given to open automatically
files at the beginning of each \TeX{} job.
\bluesubhead \cs{everycr}
A practical example is given in \TB~\on140, to inhibit a page break.
\beginverbatim
$$\everycr{\noalign{\penalty10000}}
\halign{\indent#\hfil\qquad&...\cr
If a letter is in style&then...\cr
\noalign{\vskip 2pt}
$D,D',T,T'$&text size&\cr
$S,S'$&script size&\sevenrm\cr
$\SS,\SS'$&scriptscript size&
\fiverm\cr}$$
!endverbatim
It is also used in plain, Appendix~B \on362, in the macro \cs{displ@y}.
In \TB{} file I did not find examples of use of
\cs{everymath},
\cs{everyhbox}, and
\cs{everyvbox}.
In \bluetex{} I introduced \cs{everyscript}.
My use is to allow for more than one script to be processed,
via |\everyscript{\notlastscript}|.
I also introduced \cs{everyverbatim}, and some more.
\head{Options via |\this<tag>|s}%Needed processing on the fly, so no \bluehead
First an example. I used it for the first time with verbatims.
\thisverbatim{\emc\catcode`\*=0
\catcode`\!=12 }
\beginverbatim
\thisverbatim{\emc}%enable metacode
\beginverbatim
\def\<tag>{...
...}
!endverbatim%! is the escape character
*endverbatim
Not only can metalinguistic variables be handled nicely
within verbatims, but also the changing of catcodes and
file verbatim inclusion go easy with the use of these token variables.
The verbatim suite of \bluetex{} can be used with \AllTeX, because
the mechanism is simple, and not in conflict.
File verbatim inclusion goes as follows\ftn
{It is true, that I need one escape character.}
\thisverbatim{\emc\catcode`\*=0
\catcode`\!=12 }
\beginverbatim
\thisverbatim{\input <file>}
\beginverbatim
Some text after the file.
!endverbatim
*endverbatim
\bluehead The parsing of options
Eijkhout in `\TeX{} by Topic' gives a template for coping with
optional parameters.\ftn{I adapted the macros a little.}
The work is done by \cs{OptArgCom}, with as optional
argument either the default or the one supplied.
The markup starts with \cs{Com} followed either
by a left bracket\Dash a convention to start an option\Dash
or the argument.
\thisverbatim{\emc}
\beginverbatim
\def\Com{\futurelet\testchar\MaybeOptArgCom}
\def\MaybeOptArgCom{\ifx[\testchar
\expandafter\OptArgCom\else
\expandafter\NoOptArgCom\fi}
\def\OptArgCom[#1]#2{...}
\def\NoOptArgCom{\OptArgCom[<default>]}
%with use
\Com[...]{...}!qquad!hbox!bgroup or!egroup!qquad\Com{...}
!endverbatim
With the concept of \cs{thisCom} the coding template and
markup might look like the following.
\thisverbatim{\emc}
\beginverbatim
\thisCom{<default>}
\def\Com#1{...\the\thisCom...
\thisCom{<default>}}%restore default
%with use
\thisCom{...}%Provides option(s), if any
\Com{...}
!endverbatim
Explanation.
The contents of the token variable
is available to the macro. It can be virtually anything.
At the end of the macro the default is restored.
IMHO, with all respect, the latter approach is simpler
than the parsing of optional arguments.
\bluehead Head example
\bluetex{} allows as markup
\beginverbatim
\beginhead...\endhead!qquad !hbox!bgroup or!egroup!qquad\head{ ...}
!endverbatim
And what about the coding?
In the `Paradigms: Headache?' I have shown the \bluetex{} coding
\beginverbatim
\def\beginhead{\the\prehead\bgroup\headfont}
\def\endhead{\egroup\the\posthead}
%with auxiliaries
\prehead{\vskip0pt plus2ex
\penalty-250\vskip0pt plus1ex
\bigskip\noindent}
\posthead{\medskip\nobreak
\noindent\ignorewhitespace}
%and minimal variant
\def\head#{\beginhead\bgroup
\aftergroup\endhead
\afterassignment\ignorespaces
\let\dummy=}
!endverbatim
Note that in \bluetex, I also introduced the token variables
|\pre<tag>|, and |\post<tag>|, to parameterize
the placement within context. The advantage of doing so is
that these tags have only one function and can therefore
be customized easily.\ftn
{A white lie. In \cs{report} format I also reused the headtitle
in the ToC, ToE, and in the running header.}
\bluesubhead Relation with tugboat.sty
Submissions for TUGboat need as markup for headings the following.
\beginverbatim
\head...\endhead!qquad !hbox!bgroup or!egroup!qquad\head*...*
!endverbatim
where in the short variant the spaces around the *s are neglected.
TUGboat provides as toplevel coding
\beginverbatim
\def\head{\begingroup
\def\CurrentTag{head}%
\@allowindentfalse
\@defaultoptions
\@savingargumenttrue
\def\\{\break}%
\@checkoptions}
\def\endhead{\endgraf
\ifcase\headlevel\or
\@domainhead \or
\@dosubhead \or
\@dosubsubhead\fi
\endgroup\@next}
!endverbatim
What can be seen from the above is that both codings are based
on two-part macros. The coding for TUGboat uses general
mechanisms not restricted to \cs{head},
and is therefore difficult to understand.\ftn
{An example is finding the answer to the question whether the `argument' is processed
on the fly. \cs{@savingstrue} suggests that it is stored. Try to confirm
the assumption in the code, and you will agree that even reading
the code is difficult, let alone to adapt it. To borrow
macros for use in other collections is also inhibited, as Wietse
Dol communicated to me. Of course, it is a good thing to go for
general mechanisms in macro writing. But the right balance between
metacodes and single shot coding is the royal road, IMHO, with all respect.}
Especially, when one realizes that next to the parsing of options,
the minimal variant is also handled. (The parsing looks for *s).
Clever, very clever.
But the functionality can be attained simpler, with the extra bonus of
easy maintenance and customization, IMHO, with all respect.
\bluesubhead Relation with ams.ppt
Submissions to AMS (in ams.ppt) need as markup for headings
\beginverbatim
\head...\endhead
!endverbatim
The coding reads
\beginverbatim
\outer\def\head#1\endhead{%
\add@missing\endroster
...
\add@missing\endproclaim
\penaltyandskip@{-200}\aboveheadskip
{\headfont@\raggedcenter@
\interlinepenalty\@M
#1\endgraf}\headmark{#1}%
\nobreak\vskip\belowheadskip}
%
\let\headmark\eat@
!endverbatim
The \cs{end@missing} checks whether the head occurs within the environment.
\cs{eat@} gobbles its argument.
There is no \cs{nofrillscheck}. This is done, however, in \cs{subhead}.
The coding of the check is difficult to understand, not in the least because it
allows for options.\ftn
{I was told that AMS considers to abandon \cs{nofrills} altogether.}
\bluesubhead \LaTeX's \cs{section}
The style defines \cs{section} as an invocation to \cs{@startsection}.
From latex.doc the following.
\beginverbatim
%\@startsection{name}{level}{indent}
% {beforeskip}{afterskip}{style}
% optional * [altheading]%
% {heading}
%Generic command to start a section.
%Name : e.g. subsection
%Level : a number, denoting depth of
% section e.g., chapter=1,
% section=2 etc.
%Indent: Indentation of heading from
% left margin
%Beforeskip: Absulute value is skip to
% leave above the heading.
% If negative, then paragraph
% indent of text following
% heading is suppressed.
%Afterskip : if positive then skip to leave
% below heading, else negative of
% skip to right
% of run-in heading.
%Style : commands to set style.
%If * missing then increments the counter. If
%it is present, then there should be no
%[altheading] argument. Use the counter
%`secnumdepth' whose value is the highest
%section level that is to be numbered.
!endverbatim
This is just the top of the iceberg, but generic it is for sure.
My choice would be the following.
To go first for making it as simple as possible,
and perhaps if the need is still there,
use generic coding in order to save on development and maintenance costs.
\bluehead Knuth's options after an opening tag
There is a beautiful example of allowing for options in manmac.
It is used in \TB~\on29.
All what follows after the opening tag \cs{begindisplay} up to the end-of-line
is taken as (optional) argument, and inserted in the
alignment display between \$\$ and \cs{halign}.\ftn
{No curly braces nor other opening and closings like [ and ].
And when you don't need the option functionalty you won't notice.
It does not hinder or impose on you.
Minimal markup? Yes, definitely.}
\beginverbatim
\begindisplay\hbadness10000
\hbox spread-.666667em{The badness
of this line is 100.}&
\quad(very tight)\cr
...
\enddisplay
!endverbatim
This example shows what Knuth had on his mind with respect to
options and explains why he did not introduce |\this<tag>|s.
The coding is a litlle more complicated but systematic.
Can it be applied applied throughout a format?
With \cs{beginverbatim} I stumbled upon problems in
applying options to the in-line verbatim \vrt\dots\vrt.
\bluehead Epilogue
The paradigm is that too general, monolithic, codes are difficult
to understand and to maintain.
Borrowing macros from these collections is near to impossible.
|\this<tag>| is a simple alternative for
coping with optional arguments, and is used in \bluetex.
Knuth suggested a solid naming convention for two-part macros:
|\begin<tag>|, |\end<tag>|, and
for the second step macro |\start<tag>|, if any.
This naming convention has been adopted in \bluetex,
next to |\<tag>| for one-part minimal variants.
Have fun, and all the best.
\makesignature
\pasteuptoc
\endscript