%\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}