summaryrefslogtreecommitdiff
path: root/usergrps/uktug/baskervi/5_5/hhpmark.tex
diff options
context:
space:
mode:
Diffstat (limited to 'usergrps/uktug/baskervi/5_5/hhpmark.tex')
-rw-r--r--usergrps/uktug/baskervi/5_5/hhpmark.tex832
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}