diff options
Diffstat (limited to 'usergrps/uktug/baskervi/5_5/hhpmark.tex')
-rw-r--r-- | usergrps/uktug/baskervi/5_5/hhpmark.tex | 832 |
1 files changed, 832 insertions, 0 deletions
diff --git a/usergrps/uktug/baskervi/5_5/hhpmark.tex b/usergrps/uktug/baskervi/5_5/hhpmark.tex new file mode 100644 index 0000000000..d47b0fdcd6 --- /dev/null +++ b/usergrps/uktug/baskervi/5_5/hhpmark.tex @@ -0,0 +1,832 @@ +%\usepackage{hhparmrk} % for presentation +%\usepackage{verbatim} % for verbatim displaying of examples +%\usepackage{xspace} % for ease of typing +%\usepackage{hhmuf} % used in examples +%\usepackage{amssymb} % used in examples + +\makeatletter + +% The following has been copied from my personal tools style file hhutils.sty +% (NB: This is _not_ the same file as the public style file hhutils0.sty!) + +\setcounter{errorcontextlines}{10} % For ease of debugging. +\showboxdepth=10 % For ease of debugging. +\showboxbreadth=100 % For ease of debugging. +\def\0#1.{\oldstylenums{#1}} % For ease of typing. +\def\packagename#1{{\sffamily #1}} % For consistent displaying of + % package names. To be redefined + % by the editor if desired. +\chardef\@ttbs="5C % This the only way I could figure +\def\macroname#1{{\ttfamily\@ttbs#1}} % out to get the right backslashes + % when displaying macro names + % (math \backspace is too thin). +\def\envirname#1{{\ttfamily #1}} % For consistent etc. +\def\scheiding{\par % Because I cannot help to show my + % `stamp' in and out of season. + % Remove the stamps it you cannot + % stand them. + \nobreak\addvspace{26pt plus 6pt minus 6pt}% + \nobreak\centerline{{\unitlength1pt\begin{picture}(0,0) + \thicklines + \put(-10,2.5){\line(1,-1){10}}\put(-10,2.5){\line(1,1){10}} + \put(10,2.5){\line(-1,-1){10}}\put(10,2.5){\line(-1,1){10}} + \put(-5,7.5){\line(0,-1){10}}\put(5,7.5){\line(0,-1){10}} + \put(-5,0){\line(2,1){10}}% + \qbezier(-31.8,-2.5)(-12.6,12.2)(0,12.5) + \qbezier(0,12.5)(14.2,12.8)(20.9,-2.5) + \qbezier(-31.8,-2.5)(-16.5,15.8)(0,16.1) + \qbezier(0,16.1)(16,16.4)(20.9,-2.5) + \end{picture}}}% + \addvspace{18pt plus 6pt minus 6pt}} + +\def\={\verb=} +\def\<#1>{\macroname{#1}} +\def\:{\linebreak[1]} + +% Furthermore I defined a macro for short framed verbatim: +\def\fverb{\sbox\@tempboxa\bgroup\verb} +\def\brevf{% + \egroup\leavevmode{\setlength\fboxsep{2pt}\fbox{\box\@tempboxa}} } + +% The following macros are copied from scenario.sty, with some +% modifications and simplifications, for demonstration purposes: + +\newcommand{\ForWhom}{} +\newcommand{\ForExclusive}{ + \renewcommand{\ForWhom}{`Exclusive'} + } +\newcommand{\MarkThisExclusive}[1]{% + \begin{trafficsigned*}{\trapbox:}{\small Ex}#1\end{trafficsigned*}} +\newcommand{\MarkThisCircle}[1]{% + \begin{trafficsigned*}{\ringbox:}{\small Ci}#1\end{trafficsigned*}} + +\makeatother + + +\title{The Scenario: an Efficient Document with \protect\hhparmrk} +\author[Herman Haverkort \& Frans +Goddijn]{Herman Haverkort \& Frans +Goddijn\\\emph{Email:} \texttt{herman@fgbbs.iaf.nl} \& +\texttt{goddijn@fgbbs.iaf.nl}} + +\begin{Article} + +\mufhire see carried away:{See the article about HH getting carried away, + published in \BV\ 5.4} + +\begin{abstract} +\begin{markspanned}(% + {{\sbox0{\tiny + \clap{\ringbox:{\vbox{\offinterlineskip + \hbox{\clap{$\thicksim\backsim$}} + \hbox{\clap{% + \sbox0{$\circ$\raise0.6pt\llap{$\centerdot$\kern0.4pt}}% + \copy0\,\copy0}} + \hbox{\clap{$\vartriangle$}}\kern1.5pt + \hbox{\clap{$\smile$}}}}}}% + \vbox{\offinterlineskip + \copy0 + \hbox to \wd0{\hss$\bowtie$\hss}}}}% + [\msprule]% + {\sepbox(0pt,1pt,0pt,0pt){\large$\bigtriangleup$}}% + {1em}[0pt]( +\begin{bracespanned})\}:-[0pt]{\muf:{Just a demonstration of + \hhparmrk's way of bracing and footnoting a paragraph.}}) +During work towards a flexible document as a continuous report on a wide +variety of contacts for the Meridian Arts Ensemble in New York, Frans +Goddijn felt the need to tag and mark certain paragraphs for specific +groups of readers. Herman Haverkort wrote a package for \LaTeXe, +\hhparmrk, which facilitates this by offering the possibility to set +various signs next to paragraphs. This article presents \hhparmrk, gives +examples of its use and a short manual. For the hackers among us some of +the \TeX nical tricks involved behind the scenes are glanced at. +\end{bracespanned}\end{markspanned} +\end{abstract} + + +During the process of organizing concerts for a delightful brass +quintet from New York called the Meridian Arts Ensemble I noticed that +there is at least \emph{one} aspect about playing all over the world which +causes anxiety. Namely, the fact that in many places, many people (are +supposed to) look after your interests and it's very hard to keep track +of who is doing what. + +I used my knowledge of \LaTeX\ to generate reports on all my Meridian +activities. Instead of building up a heap of separate emails, notes, +letters and memos I wrote or compiled them all as \verb|\sections| and +\verb|\subsections| into the same master document, which I entitled {\sc the +scenario}. With \emph{CorelDraw!} I designed a title page, \LaTeX\ took +care of the table of contents and an elaborate index, and gradually I +was generating a tight mass of information which I could print out at +will and send to the Meridians. + +This \LaTeX\ product impressed them, as they'd never before seen such a +`roadmap' of all that was done or not yet done in their interest. This +helped them in making the decision to leave a professional +booking agent and let me coordinate all further +activities in this part of the world! +{\sc the scenario} quickly +grew in size to over fifty pages filled with valuable information +about how to initiate contacts with promotors and presentors in concert +halls and other venues. The advantage of using \LaTeX\ over some other +typesetting or word processing tools is that it's fast and simple to +copy plain \textsc{ascii} emails into it. For instance, the tuba player of +the group uses the Internet to send me updates for the {\tt tabular} +listing their concert dates. The same goes for newspaper reviews and +incoming faxes, which I run through a scanner with \textsc{ocr} to transfer it +into electronic text. To brighten up the text page, I sometimes create a +graphic scan of a hand written quote of musical score or a concert +program. + +Over the weeks, the book even got its own `gossip' section, and +soon it turned into a kind of family scrapbook, besides building up the +more formal data. + +By this time, the new print looked so handsome that it was a shame not +to use it for a wider range of readers. Other groups could benefit from +the many addresses listed in {\sc the scenario}, and some fans had heard +of its existence and were keen to get a copy of the book with all its +\emph{inside information}. + +\includegraphics[width=\linewidth]{zappa} +\begin{center} +\textsf{A stylized portrait of Frank Zappa. The Meridian Arts +Ensemble is especially renowned for their interpretations of Zappa's +compositions, arranged by Jon Nelson.}\end{center} + +How to go about this? I would now need three versions of the document. +One full version with all info for me and the Meridians, one slimmed +down version where any explicitly confidential text would be left out +and one minimal version especially geared towards concert hall +programmers with only the basic material (introduction, biographical +info, reviews and the like). + +Luckily, I had just introduced a young man to \LaTeX. I think that every +\TeX\ user has made attempts, with more or less success, to convince +others of the beauty and pleasures of \TeX\ and I am no exception to +this rule. Most of the time, people have no clue what I'm talking about. +Sometimes, one buys the 4all\TeX\ {\sc cd-rom} and installs it but +rarely an avid new user is born. This Herman Haverkort was different: my +letter telling him about \LaTeX\ happened to reach him on a Friday when +he was most bitterly sick of his `WordPerfect' software and he +immediately took action. He got the software from me, installed it, read +the \TeX book from screen ignoring all \emph{dangerous bend}-signs and +the next week he devoured the printed book itself. + +Herman recognized my problem and as he had a similar project at hand, he +created a new style file for us, called \hhparmrk. + +Now I could brand some paragraphs for \emph{exclusive} readership, others +for a \emph{circle} of interested readers and the rest was for +\emph{wide} distribution. In the `Wide' version, paragraphs of the other +two categories should vanish automatically (actually there is a fourth +version, `Concise', which is a `Circle' version limited to +the very basic information). + +First, I took macros for the \emph{disappearing acts} from the +\packagename{comment} package but a little later I figured out an easier +way, by using a macro with a variable and never using that +variable! Here is the disappearing act: +% HH % In de twee regels hierboven zou in plaats van "variable" eigenlijk +% HH % horen te staan: "parameter" (vermoed ik). In de rest van de tekst +% HH % zou "variable" eigenlijk moeten worden vervangen door: "argument". +% HH % Beslis jij maar wat je doet: zolang het begrijpelijk is (en dat is het +% HH % nu wel) vind ik het eigenlijk allemaal best. + +\begin{verbatim} +\newcommand{\LeaveOut}[1]{} +\end{verbatim} + +\verb|\LeaveOut{Sh*! Wish I hadn't said that}| enables me to put in some +lengthy paragraphs that I don't (yet) intend to really use in print, but +want to have there in the source file as my own private comments, or I +can have \TeX\ ignore portions of text I might want to use later. + +In the `Circle' version, +only the \emph{exclusive} texts must disappear and some more or less +confidential paragraphs must be marked accordingly. +In the `Exclusive' version, everything is visible but the reader must be +able to see what parts will be occluded for others. + +Now look at the following new commands. At first they are without any use, +later on they get their tasks assigned. Look at them, bland and +expressionless like babies, with only their names to distinguish them +from other creations\ldots + +\begin{verbatim} +\newcommand{\ForWhom}{} +\newcommand{\Circle}[1]{} +\newcommand{\Exclusive}[1]{} +\newcommand{\EndConcise}{} +\end{verbatim} + +This is what they get to do in life:\\ +\verb|\ForWhom| will remember for whom the current version is made.\\ +\verb|\Circle| will be a macro with one variable at a time, namely a +paragraph that must be left out in the `Wide' version and marked as +`Circle' in the other versions.\\ +\verb|\Exclusive| will also be a macro with one variable at a time, +this time a paragraph that must be left out in the `Wide' \emph{and} in +the `Circle' versions and marked as `Exclusive' in the `Exclusive' +version.\\ +\verb|\EndConcise| will normally mean nothing, but the command is placed +at a point in the text where it must end with a new page and an index +if I want to create a `Concise' version. + +Then the definitions of the different standard versions: + +\begin{verbatim} +\newcommand{\ForExclusive}{ + \renewcommand{\ForWhom}{`Exclusive'} + \renewcommand{\Exclusive}[1]{% + \MarkThisExclusive{##1}} + \renewcommand{\Circle}[1]{% + \MarkThisCircle{##1}} + } +\end{verbatim} + +What happened above is that \verb|ForWhom| will now remember it's for +`Exclusive' use, and both `Exclusive' and `Circle' paragraphs are +classified as such in the margin. + +\begin{verbatim} +\newcommand{\ForCircle}{ + \renewcommand{\ForWhom}{`Circle'} + \renewcommand{\Exclusive}[1]{(\ldots)} + \renewcommand{\Circle}[1]{% + \MarkThisCircle{##1}} + } +\end{verbatim} + +What happened above is that \verb|ForWhom| will now remember it's for +`Circle' use. `Exclusive' paragraphs are ignored and `(\ldots)' is +printed in their place, while `Circle' paragraphs are classified as such +in the margin. + +\begin{verbatim} +\newcommand{\Concise}{ + \renewcommand{\EndConcise}{% + \newpage \printindex \end{document}} + \renewcommand{\ForWhom}{concise `Circle'} + \renewcommand{\Exclusive}[1]{(\ldots)} + \renewcommand{\Circle}[1]{% + \MarkThisCircle{##1}} + } +\end{verbatim} + +What happened above is that \verb|ForWhom| will now remember it's for +`concise Circle' use. `Exclusive' paragraphs are ignored and `(\ldots)' is +printed in their place, while `Circle' paragraphs are classified as such +in the margin. Furthermore, at the place where the `dummy' macro +\verb|\EndConcise| was loitering, it is now told to end the document +neatly with a new page and an index. + +\begin{verbatim} +\newcommand{\ForWide}{ + \renewcommand{\ForWhom}{`Wide'} + \renewcommand{\Exclusive}[1]{(\ldots)} + \renewcommand{\Circle}[1]{(\ldots)} + } +\end{verbatim} + +The long dull version. Only harmless material is printed, and lots +of it, even beyond the \verb|\EndConcise| macro. + +\begin{verbatim} +\newcommand{\MarkThisExclusive}[1]{% + \begin{trafficsigned*}{\trapbox:}{\small Ex} + #1\end{trafficsigned*}} +\newcommand{\MarkThisCircle}[1]{% + \begin{trafficsigned*}{\ringbox:}{\small Ci} + #1\end{trafficsigned*}} +\end{verbatim} + +The above two lines control all markings in the text, using new macros +and environments which are defined in \hhparmrk. + +\begin{verbatim} +This text may be seen by everybody. + +\Circle{This text may be seen, marked with a + circled `Ci', by a certain circle.} + +\Exclusive{This text may only be seen, marked + with a `Ex' in a trapezoid box, by a + small group of readers exclusively.} +\end{verbatim} + +I am now able to change the look and size of the document by activating +one of the following commands (while commenting out the others): + +\begin{verbatim} +%\ForExclusive +%\ForCircle +%\ForWide +\Concise +\end{verbatim} + +Herman Haverkort will, later on in this article, explain the new and +hitherto unknown commands here. I'm glad he does. They fill me with +wonder. I began creating the macros only after looking hard and intensely +into the manual material\ldots\ and immediately after I'd finished writing +them, I stacked them away in a separate style file . That way I don't have +to see them so often and I can try to forget they're there at all! + +Now I will first show you one of the first pages, where I explain to the +readers what versions there are and what version they're holding. Next, +I will try my luck at displaying the result for you\ldots + +\verbatiminput{hhpmsca.tex} + +which results in: + +\bigskip\hrule height 1pt\nobreak + +\input{hhpmsca.tex}\nobreak + +\bigskip\hrule height 1pt + +\scheiding + +The \hhparmrk kernel consists of the environments \envirname{bracespanned} +and \envirname{markspanned}, which I will present now, starting with +\envirname{bracespanned}. + +\section{\envirname{bracespanned}} + +\input{hhpmbsa.tex} % The environment +\envirname{bracespanned} can be used to set paragraphs +braced like this one. This paragraph is done with: + +\verbatiminput{hhpmbsa.tex} + +\ldots\ concluded by: + +\verbatiminput{hhpmbsb.tex} + +The nasty details which determine the way of bracing are all specified +just after \=\begin{bracespanned}=; the concluding \=\end{bracespanned}= is +always as straightforward as % demonstrated here. +\input{hhpmbsb.tex} + +You might suspect that the left brace and comment (``FG'' in the above +example) are specified between left parentheses, while the right brace +and comment are specified between right parentheses. Well, that is right. +You do not have to specify both left and right stuff: you may leave +one of them out, as in some of the examples below. The following paragraphs +will all start with a box containing its bracing specification, that is: +all that appears between \=\begin{bracespanned}= and the text +of the paragraph. + +\begin{bracespanned}){\}}:-{\muf:{Just an example}}) +\fverb=){\}}:-{\muf:{Just an example}})=\brevf +Instead of the comments ``FG'' and ``HH'' in the above example, you can +of course specify whatever you want for a comment, for example a footnote. +This paragraph provides an example using the \<muf> footnote macro, which +is defined in the \hhmuf package\rlap{.}\muf see carried away:{} +If you want to use standard footnotes, note that all that is +spanned by \envirname{bracespanned} and the comments are so-called +forbidden environments. To set a footnote you would have +to use \<footnotemark> and \<footnotetext>; just using \<footnote> +would not work. +\end{bracespanned} + +\begin{bracespanned}){(}:-{}) +\fverb=){(}:-{})=\brevf +This paragraph illustrates that any extendable mathematical delimiter +symbols can be used instead of braces, even symbols which are pointing +the `wrong' way. Just replace the \={\{}= or \={\}}= in the example +above by \={(}=, as in this example, or whatever symbol you like. +\end{bracespanned} + +\begin{bracespanned}){\}}:{65pt}{This may be read by fiends and friends}) +\fverb=){\}}:{65pt}{This= \ldots\ \=friends})=\brevf +The \=:-= in the examples above specifies the width of the spanning +symbol plus comment. \=:-= stands for the natural width of the symbol +with comment, which usually satisfies. Another possible width +specification is a colon followed by a braced dimension, like +\=:{65pt}=. Such a specification fixes the width of the symbol plus +comment, thus enabling multi-line comments, like demonstrated here. +\end{bracespanned} + +\begin{bracespanned}){]}{ExampleId}:{ex. i}) +\fverb=){]}{ExampleId}:{ex. i})=\brevf +Sometimes it may be desirable to have the comments of several spanned +paragraphs set all to the same width, thus leaving equal line widths +for the spanned paragraphs. This can be accomplished by +giving a width specification which consists of some braced identifier +followed by a colon. The identifier may be chosen freely. +\end{bracespanned} + +\begin{bracespanned}){]}{ExampleId}:{ex. ii}) +\fverb=){]}{ExampleId}:{ex. ii})=\brevf +The previous paragraph and this one get the same width identifier +(\=ExampleId=) so that their comments are set to the same width: +the natural width of the widest. As a result, the text bodies of +both paragraphs are equally wide. However, in general you have to +compile your document twice to get this result. If a second run +may be necessary, the \hhunits package issues a warning ``Unit +values may have changed. Rerun to get them right.'' +\end{bracespanned} + +\begin{bracespanned}({\|}:-[50pt]{Gosh!}( +\fverb=({\|}:-[50pt]{Gosh!}(=\brevf +In the examples above paragraphs were indented on the sides to make room +for the spanning symbols and comments. The amount of indention was +automatically determined by the \hhparmrk macros. This automatic +determination can be overruled by specifying the amount of indention +in a bracketed optional argument, given between the width +specification and the comment. This paragraph provides an example: +it is indented exactly 50pt. Specifying a 0pt indention +would cause the spanning symbol and the comment to be set in the +margin. +\end{bracespanned} + +\begin{bracespanned}([:-()]:-) +\fverb=([:-()]:-)=\brevf +\TeX\ hackers who know when braces can be omitted are able to specify +the way of spanning a paragraph quite elegantly --- I think --- as +demonstrated by this paragraph. +\end{bracespanned} + +\section{\envirname{markspanned}} + +\begin{markspanned}% +({\sc start}[\msprule]{\sc finish}{10pt}( +The environment +\envirname{markspanned} can be used to set three-part marks +next to paragraphs. Such a mark consists of an upper part, a +lower part, and a fill part in between. The upper and lower +part have fixed size, but the fill part can be stretched so +that the assembled mark spans the entire paragraph. This paragraph +provides a simple example. +\end{markspanned} + +The above paragraph is typeset with: + +\begin{verbatim} +\begin{markspanned}% +({\sc start}[\msprule]{\sc finish}{10pt}( + The environment \envirname{markspanned} can + : : : : : : + This paragraph provides a simple example. +\end{markspanned} +\end{verbatim} + +In the above example an upper part, a fill, a lower part and the mark +seperation are successively specified. The fill is the \hhparmrk +macro \<msprule>, which connects the upper and the lower part +by a rule. The 10pt mark seperation determines the smallest +distance between the text and the three-part mark. + +The nasty details which determine the way of marking are all specified +just after \=\begin{markspanned}=; the concluding \=\end{markspanned}= is +always as straightforward as demonstrated above. The following paragraphs +will all start with a box containing its marking specification, that is: +all that appears between \=\begin{markspanned}= and the text +of the paragraph. + +\begin{markspanned}({\sc st}[\msprule]{\sc fi}[r]{10pt}( +\fverb=({\sc st}[\msprule]{\sc fi}[r]{10pt}(=\brevf +In the example above the mark parts are centred with respect to each +other. Instead of centring one can force left or right alignment by +means of \=[l]= or \=[r]= just after the definition of the lower +part. This paragraph gives an example of right alignment. +\end{markspanned} + +Until now marked paragraphs were automatically indented just enough +to make room for the marks so that they did not stick out into the +margins. Like with \envirname{bracespanned} one can control the +amount of indention `manually' by specifying an optional argument, +just after the mark seperation. + +\begin{markspanned}({$\cap$}{$\cup$}{5pt}[20pt]( +\fverb=({$\cap$}{$\cup$}{5pt}[20pt](=\brevf +This paragraph provides an example. +It is indented exactly 20pt. This paragraph also shows that the +fill part of a mark is optional and may be left out. +\end{markspanned} + +\begin{markspanned}({$/$}{$\backslash$}{5pt}(){$\backslash$}{$/$}{5pt}) +\fverb=({$/$}{\bs}{5pt}(){\bs}{$/$}{5pt})=\brevf +(\<bs> assumed to be defined as \=$\backslash$=) +Of course three-part marks could be set on the right by using right +parentheses instead of left ones, just like with \envirname{bracespanned}. +Three-part marks on both sides are possible too, like demonstrated here. +\end{markspanned} + +\subsection{More about the Fill Part} +As shown in the above examples, the second argument of a three-part mark +specification determines the fill part of the mark. You may omit this +specification: in that case an empty fill is used. Besides \<msprule> and +the empty fill one could use any desired self-made fill as long as the +following is regarded:\begin{itemize} +\item the fill should be a macro that takes one argument: the required + size. For example \<msprule> is defined by \=\newcommand=\:% + \=\msprule=\:\=[1]{\vrule= \=height= \=#1= \=width= + \=\fboxrule=\:\=}=. +\item the width of the fill is not taken in account when determining the + positioning of the mark. Therefore the width of the fill should not + be greater than both the width of the upper part and the width + of the lower part of the three-part mark. +\end{itemize} + +\subsection{Traffic Signs} + +\hhparmrk contains the following definition (shown here in syntactically +simplified version): + +\verbatiminput{hhpmtsa.tex} + +\begin{trafficsigned*}{\trapbox:}{A} +\fverb=\begin{trafficsigned*}{\trapbox:}{A}=\brevf +The environment \envirname{trafficsigned*} produces a three-part mark on +the left which forces the signed text to indent. Its upper part is +the second argument, boxed by the \hhflxbox macro +\<separbox>\muf see carried away:{} +and the tokens specified by the first +argument. These are typically framing macros like \=\trapbox:= (defined +in \hhparmrk; sets a trapezium frame), \=\ringbox:= (defined in +\hhflxbox; sets a circle frame), or \=\setlength=\:\=\fboxsep=\:% +\={0pt}\fbox= (sets +a rectangular frame). These paragraphs show some possible results. +The \TeX\ code used to start each paragraph is shown in the boxes at the +beginnings. Each paragraph is ended in the source file by +\=\end{trafficsigned*}=.% +\end{trafficsigned*} + +\begin{trafficsigned*}{\ringbox:}{B} +\fverb=\begin{trafficsigned*}{\ringbox:}{B}=\brevf +Before the \=\end=\:\={markspanned}= in +the definition of \envirname{trafficsigned*} a conditional \<strut> +is added. This is to prevent +the foot of the sign from ostensibly floating according to the +depth of the last line of a signed paragraph. +% HH % toegevoegd: +The \<scopecorrection> +is not really needed in most cases but it guards against some rare +mysterious errors. See the section about \emph{\TeX nical Details}, +subsection \emph{\hhparmrk: Parallel Marks?} for explanation.% +\end{trafficsigned*} + +\begin{trafficsigned*}{\setlength\fboxsep{0pt}\fbox}{C} +\fverb==\ldots\ \=*}{\setlength\fboxsep{0pt}\fbox}{C}=\brevf +Besides \envirname{trafficsigned*} there exists a similar environment +\envirname{trafficsigned} which sets the traffic sign in the left margin. +To avoid letter-traffical collisions it is not demonstrated here.% +\end{trafficsigned*} + +\section{\TeX nical Details} + +I will not present the definition of \envirname{bracespanned} here: it +is too long and complicated. There is lots of fuss in it, caused by the +need or wish to parse a lot of obligatory and optional arguments which +determine the exact way of bracing. However, I would like to lift a +corner of the veil which covers \envirname{bracespanned}, to give +hackers some idea of what is going on behind the scenes. Maybe, if +I am lucky, there is some hacker out there who will be highly amazed +by unnecessary complexity in my approach, and will offer me +a simpler approach instead. + +\subsection{Fooling \TeX's Gluing} + +My first try to build a useful \envirname{bracespanned} environment or +macro consisted of straightforward use of a mathematical display. +It is not difficult to set a brace spanning a box with multiple lines +of text in a mathematical display environment. +Alas that did not work out properly in all cases. +When \envirname{bracespanned} text was surrounded immediately by normal +text, the interline skip between the +top spanned line and the first unspanned line above was too small, as +was the distance between the bottom spanned line and the first unspanned +line below. \TeX\ considered the whole mathematical display to be one +unusually high line of text. Therefore \TeX\ did its very best to squeeze +the display in at the place of one normal text line, although the display +actually contained several lines. + +So I decided that I had to fool \TeX\ a bit. I constructed a mathematical +display as before, but now I boxed it. Then I typeset the spanned text again +behind the scenes, now using \<vtop>, to determine the height of the +first line. I then shifted down the boxed display to make it have that same +height. Finally I typeset the spanned text a third time behind the scenes, now +using \<vbox>, to determine the depth of the last line of spanned text. +Then I would insert the display, which had the height of its first line of +text, and fool \TeX\ by setting \<prevdepth> to the depth of the last line. +\TeX\ still considered the display to be a single high line, +but I made \TeX\ `think', with respect to setting interline glue, that +the display had the height of its top line and the depth of its bottom +line, as if all lines in between were not there. + +The approach described above had a major disadvantage: the spanned text +was typeset three times. This was not only inefficient; it was also +error-prone. For example: if a counter was stepped in the spanned +text, then it was stepped three times. I solved this by boxing +the spanned text once, using \<vtop>. Then I made a centred copy of +the resulting box, a \<vphantom> of which I used to set the braces in +mathematical displays. +I shifted the displays down to make them have the same height as the +\<vtop>ed text, so that I could put the displays and the \<vtop>ed text +together. Finally I made a copy of the \<vtop>ed text, which I unboxed +to get its last line with \<lastbox> so that I could examine its depth. +Then the remaining part of the procedure was like described in the +previous paragraph. + +All this resulted in the \TeX\ code below (shown here +abridged and simplified): + +\begin{verbatim} + %Box what has to be spanned in \@tempboxa: +\setbox\@tempboxa\vtop{#1}% + %Make a centred copy of the result: +\sbox\@tempboxd{\ensuremath{\vcenter{% + \copy\@tempboxa}}}% + %Determine how much the displays should be + %shifted down; store result in \@tempdima: +\setlength\@tempdima{\ht\@tempboxd}% +\addtolength\@tempdima{-\ht\@tempboxa}% + %Set the left brace in \@tempboxb: +\sbox\@tempboxb{% + \lower\@tempdima\hbox{% + %... + %in hhparmrk.sty one finds at this place + %the math display stuff which sets the left + %brace, using \vphantom{\copy\@tempboxd} to + %determine the height + %...}}% + %Set the right brace in \@tempboxc: +\sbox\@tempboxc{% + %... + %same story + %...}% + %Now determine the depth of the last line: + %Make a discardable copy of \@tempboxa in + %\@discabox: +\setbox\@discabox\copy\@tempboxa +\setbox\@discabox\vbox{% + %Get the last line: + \unvbox\@discabox + \setbox\@discabox\lastbox + %Save its depth in \h@virtualdepth: + \global\h@virtualdepth\dp\@discabox}% + %Finally put it all together: +\hbox{\llap{\box\@tempboxb}% + \box\@tempboxa\rlap{\box\@tempboxc}}% + %Fool TeX's gluing: +\prevdepth\h@virtualdepth +\end{verbatim} + +\subsection{Banishing Stubborn White Space} + +Some environments like to surround themselves by vertical white space. +Section headings have the same tendency. But when complete (sub)sections +are spanned by \envirname{bracespanned}, we do not want to get results +like this: + +\begin{bracespanned}(\{:-( +\small +\kern \baselineskip +\noindent\textbf{Heading}\par +\kern .5\baselineskip +\noindent lots of blah\ldots +\end{bracespanned} + +It looks ugly. Vertical space added in the beginning of a spanned passage +should be squeezed out: it should be set on top of the span, instead of +\emph{in} the span. This is implemented as follows. In the beginning of +a passage being boxed \<prevdepth> is set to $-4774\hbox{pt}$ +(just some value smaller than $-1000\hbox{pt}$. \<addvspace> is redefined +to set vertical space only when \<prevdepth> is greater than $-4774\hbox{pt}$, +that is: when we are not in the beginning of the spanned passage anymore. +If \<prevdepth> still equals $-4774\hbox{pt}$ then the vertical space is +added to a box register which holds the squeezed out space. +After the complete passage has been boxed, +first the squeezed out space register is unboxed and added to the main +vertical list, and then the boxed passage is spanned and set. +This results in the following \TeX\ code for setting brace spans: + +\begin{verbatim} + %Box what has to be spanned in \@tempboxa: +\setbox\@tempboxa\vtop{\topsqueezeout #1}% + %Make a centred copy etc. (see the previous + %listing) + %... + %Finally put it all together: +\topsqueezein +\hbox{\llap{\box\@tempboxb}% + \box\@tempboxa\rlap{\box\@tempboxc}}% + %Fool TeX's gluing: +\prevdepth\h@virtualdepth +\end{verbatim} + +\noindent where \<topsqueezeout> takes care of redefining \<addvspace>, +and \<topsqueezein> adds the accumulated squeezed out space: + +\begin{verbatim} +\newbox\h@tsqo@squeeze + +\def\topsqueezeout{% + % Save original \addvspace: + \let\h@tsqo@addvspace=\addvspace + % Redefine \addvspace: + \def\addvspace##1{% + \ifdim\prevdepth>-4774pt\relax + % If we are not in the beginning of the + % box anymore, call original \addvspace: + \h@tsqo@addvspace{##1}% + \else + % else add space to box register which + % holds the squeezed out space: + \global\setbox\h@tsqo@squeeze\vbox{% + \unvbox\h@tsqo@squeeze + \h@tsqo@addvspace{##1}} + \fi}% + % Initialize box holding squeezed out space: + \global\setbox\h@tsqo@squeeze\vbox{}% + % Set \prevdepth to -4774pt to indicate the + % beginning of the box: + \setlength\prevdepth{-4774pt}} + +\def\topsqueezein{\unvbox\h@tsqo@squeeze} +\end{verbatim} + +The real implementation in \hhparmrk is more complex: it also redefines +\<addpenalty>, and it contains more fuss to account for nested +\envirname{bracespanned} environments. + +At the bottom of the spanned passage vertical space should be +squeezed out as well. This is also done using a box register to hold +the squeezed out space. After the passage being boxed has been +entirely added to the box in which it is set, the space +at the end is examined with \<lastskip>. The space is removed with +\<unskip> and added to the box holding squeezed out space. +Because there may +be multiple skips at the end of the passage this procedure is repeated +until \<lastskip> returned zero three times. I could not find +a way to distinguish zero skips and no skips: \<lastskip> returns +zero in both cases. Since three consecutive zero skips seem +to be unlikely, the algorithm terminates when \<lastskip> +yielded zero three times consecutively. + +\subsection{\hhparmrk: Parallel Marks?} + +\hhparmrk actually stands for: \emph{Herman Haverkort's parallel +marks}. The `philosophy' behind this is that \hhparmrk's marks +should not interfere with the hierarchical structure of the document. +Ideally marked and unmarked passages are typeset and processed +just like they normally are, except for the presence of the marks. + +In practice this is not fully attainable. First it is probably +inevitable to set each marked passage as a separate paragraph, +and that is what is done indeed. + +A second problem is that marked passages +are set in internal vertical mode, which causes footnotes and +marginal notes to disappear. For \hhmuf's style\muf see carried away:{} +footnotes this problem has been solved. For standard footnotes this problem +can be solved, but I did not bother to do it yet. + +A third problem is the grouping invoked by using environments and +boxing commands. This grouping causes the scope of local assignments +in marked passages to be reduced. Because that is exactly what is +expected when \LaTeX's environments are used I decided not to do much +about it, to avoid confusion. However, I built in a +small `scope correction' which suppresses the scope reduction of +assignments to \<everypar>, \<par>, \<@par> and \<@currentlabel>. +The first three should not be really necessary, but the handling +of \<@currentlabel> can be useful when section headings or the like +are spanned for some reason. The scope correction can be activated +by the macro \<scopecorrection>, which is defined as follows: + +\begin{verbatim} +\def\scopecorrection{% + \h@savelocals + \h@restorelocals} + +\def\h@savelocals{% + \global\h@sc@everypar=\everypar + \global\let\h@sc@par=\par + \global\let\h@sc@@par=\@par + \global\let\h@sc@@currentlabel= + \@currentlabel} + +\def\h@restorelocals{% + \aftergroup\h@@restorelocals} +\def\h@@restorelocals{% + \everypar=\h@sc@everypar + \let\par=\h@sc@par + \let\@par=\h@sc@@par + \let\@currentlabel=\h@sc@@currentlabel} +\end{verbatim} + +\section{Where to Get what Files?} + +To be able to use \hhparmrk, you should also have the packages +\hhflxbox, \hhunits, \hhqueue and \hhutils0 available. These packages +are automatically loaded by \hhparmrk. All files needed can be +obtained from {\sc fgbbs}\muf:{{\sc fgbbs} --- tel. +31 (0)26 3217041} +by requesting the file {\ttfamily hh.arj}. They are +on {\sc ctan} in \texttt{macros/latex/contrib/supported/hh}. Note that +\LaTeX \02..\009. versions are not available. + +\mufend{} +\end{Article} |