% border.doc  --- version 1.0 (21 October 1991)
% This is the documentation for border.tex.
% To read this file, process it with (plain) TeX: tex border.doc
% (To do that, you need both border.tex and manmac.tex. The latter has
% the macros for typesetting the TeXbook, as explained in appendix E.
% It comes free with the standard distribution of TeX.)
%
% NOTE: Processing this file with TeX will create empty files
%       index.tex and answers.tex in your directory. And if you
%	have a file pages.tex in your directory, TeX will probably
%	get very confused.
%	The manmac format will try to load a font called cmman; if
%	TeX complains that it cannot find that font you can savely
%	ignore that, since the font is not actually used.
%
% This file: copyright (c) 1991  Marcel van der Goot.
%	You may redistribute this file and printed versions of it.
%
% original: csvax.cs.caltech.edu [131.215.131.131] in pub/tex
%	    (use anonymous ftp). Also in various archives.
%
% Marcel van der Goot
% marcel@cs.caltech.edu
%   Caltech 256--80
%   Pasadena, CA 91125
%   (818) 356--4603

% ------ definitions for manual pages:
% The documentation is typeset using Knuth's ``manmac'' macros, with a
% few additional things defined here. You are free to use or adapt these
% extra definitions.

\input manmac % the macros used for typesetting The TeXbook (appendix E)
\catcode`^=7 % manmac makes ^ active for creating an index
	% we don't make an index, and we need ^ to be non-active

{\catcode`\^^M=12 \endlinechar=-1 % 12 = other
\long\gdef\manpagehead#1^^M#2^^M#3^^M^^M% tex-file, description, version
   {\egroup % matches \bgroup in \manpage
    \par\vfill\eject
    \edef\rhead{\manualname: #1\unskip}%
    \setbox1=\hbox{\titlefont #1\quad}%
    \setbox3=\vtop{\advance\hsize by-\wd1 \parindent=0pt \raggedright
		   #2\par
		   #3\par
		   \cnotice
		  }%
    \line{\box1\box3}%
    \bigskip\bigskip\bigskip\noindent
   }%
} % restore \catcode`\^^M

\outer\def\manpage
   {\bgroup\catcode`\^^M=12
    \manpagehead
   }

\hsize=6.5in\vsize=8.9in % default plain TeX values
\pagewidth=\hsize \pageheight=\vsize

\def\cnotice{Copyright \copyright\ 1991 Marcel R. van der Goot}
\def\manualname{Midnight Macros}

% LaTeX logo, from latex.tex (except for the capital `A': manmac
% doesn't have a real smallcaps font)
\def\LaTeX{{\rm L\kern-.36em\raise.3ex\hbox{\sc A}\kern-.15em
    T\kern-.1667em\lower.7ex\hbox{E}\kern-.125emX}}

\tenpoint

% (end of extra definitions)

% -------------------- border.doc:

\input Midnight/border % change this to refer to border.tex on your system

\def\boxelm#1%
   {\hbox{\vrule width .2mm
	  \vbox to 10mm{\hrule height.2mm
			\hbox to9.8mm{}\vfil
			\hrule height.2mm}%
	  \vrule width .2mm
   }}

\def\bulletelm#1%
   {\ifcase#1%
	   \roundcorners0%
	\or\hbox to1cm{\hss$\bullet$\hss}%
	\or\roundcorners2%
    \fi
   }

\def\cloudelm#1%
   {\hbox{\roundcorners0\roundcorners2}}

\def\numberelm#1%
   {\vbox to12pt{\vss
		 \hbox to12pt{\hss\number#1\hss}
		 \vss
   }}

\pageno=17 % follows styledef.doc

\manpage border.tex
Macros to typeset borders.
Version: 1.0 (21 October 1991) (doc: 23 Oct 1991)

\setborder[\hsize,1em,\smallskipamount]\border{\noindent
The macros described in this manual section are used to typeset borders,
such as the border around this paragraph. These borders are built from
different ``characters'': in this example from quarter circles for the corners
and straight line segments for the edges, but, given an appropriate font,
other borders can also be typeset. (Below we explain how a border
font must be designed in order to be useful with these macros.) Before
any of the macros described below can be used, you must |\input|
border.tex.*
}

There\footnote{}{* Border.tex also works with \LaTeX.}
% if the \footnote is done within \setborder, it gets lost
are several ways of typesetting borders, depending on the characters
that form the border. Macros such as |\border|
create a vbox of specified height and width (the depth is always zero),
containing only the border. Typesetting text within a border is done by
creating a box with the text and superimposing it on the box with the border,
as explained later. The types of border we will now describe differ in the
way they compose characters to build a border; the choice of the characters
is determined by another macro (|\borderelm|). The border around the
previous paragraph was typeset with |\border|. It is built from eight
different characters: `\roundcorners0', `\roundcorners1', and
`\roundcorners2' for the top; `\roundcorners3' and `\roundcorners4' for the
center; and `\roundcorners5', `\roundcorners6', and `\roundcorners7' for the
bottom. |\border| takes two arguments, the height and the width of the border.
\begintt
\border{2cm}{10cm}
\endtt
creates a border like this:
$$\border{2cm}{10cm}$$
It is a vbox with height $2$ cm, depth $0$, and width $10$ cm.

In order to create a border of the exact specified dimensions, some characters
may need to overlap. Suppose we built a border from the following character,
a $1$ cm by $1$ cm box:
$$\boxelm0$$
The following is the
border created by |\border{4.8cm}{10.5cm}|:
$$
\let\borderelm=\boxelm
\border{4.8cm}{10.5cm}
$$
As you see, some of the boxes overlap, in order to get the specified
dimensions. This overlap is always between the edge elements, there is never
overlap with the corner elements (unless the size is too small).
In fact, the overlap is always with
the edge elements that are closest to the corners. (|\border| always sets
at least one edge element for each edge.)

|\border| works fine if the edge elements can overlap, which basically
restricts them to be ``rule like.'' There is an alternative to |\border|,
called |\xborder|. It is used in the same way as |\border|, but the exact
size is obtained by putting extra space
between the elements, rather than overlapping them. Suppose we build a
border with the
same corner elements as before, but with the edge built from ``bullets''
rather than straight line segments. The top element consists of a bullet
centered in a $1$ cm wide box. Here are the top lines obtained from
|\border{...}{4.5cm}| and |\xborder{...}{4.5cm}|, respectively.
\let\borderelm=\bulletelm
$$
\line{\hss\hborder{4.5cm}012\qquad\qquad\hxborder{4.5cm}012\hss}
$$
In case of |\xborder|, the proper vertical size is also obtained by spacing.

Some border characters, however, need to abut in order to form
a border. For instance, suppose we want to make a ``cloud like'' border,
where the top corners and top edge elements are all `\cloudelm0'
In this case, |\border{...}{1.6cm}| and |\xborder{...}{1.8cm}| give
\let\borderelm=\cloudelm
$$\line{\hss
\hborder{1.6cm}012\qquad and\qquad\hxborder{1.8cm}012%
\hss}$$
Clearly, neither solution works very well.
For this case there are two other macros, |\minusborder| and |\plusborder|.
They take the same arguments as |\border|, but produce a box of rounded
dimensions rather than of the exact size. The border is built by abutting
the elements. |\minusborder| rounds the size down, whereas |\plusborder| rounds
the size up. |\minusborder{...}{1.8cm}| and |\plusborder{...}{1.8cm}| give
$$\line{\hss
\hminusborder{1.8cm}012\qquad and\qquad\hplusborder{1.8cm}012%
\hss}$$

\setbox0=\hbox{\it width}\setbox2=\hbox{\it hspace}\setbox4=\hbox{\it vspace}

The above macros all generate empty borders. Typically, one wants to put some
text in the border. There is one macro to make that easy, |\setborder|. It
is called as follows:
\begintt
\setborder[|copy0, |copy2, |copy4]\border{ ... }
\endtt
where the |...| stands for the text that must be boxed. In this case, |\border|
will be used to create the border, but you can also use |\xborder| etc.
The border will be \copy0\ wide (or a rounded value); the height of the
border is determined by the amount of text. The text itself is first
broken in paragraphs and lines, as usual in \TeX. The width of the lines
is $\copy0 - 2\cdot\copy2$. The text is than put in the border with
\copy4\ space at the top and at the bottom, and \copy2\ space at the left and
at the right hand sides.
For instance, the first paragraph of this manual section was set with
\begintt
\setborder[\hsize,1em,\smallskipamount]\border
{\noindent The macros described ...
 ....
}
\endtt
The \copy0\ and \copy2\ must be dimensions; \copy4\ can be a dimension or
a glue amount (without |\vskip|).

\danger With |\setborder|, the text between braces, |{...}|, is read
in the same way as when you write |\vbox {...}|. (You can use |\bgroup| and
|\egroup| instead of the braces.) The text is {\it not\/} an argument of
|\setborder|, which is important if it contains catcode changes. You can
change the paragraph shape, or have more than one paragraph of text.
\let\borderelm=\roundcorners
$$\setborder[10cm, 1cm, 4mm]\border{
\parindent=0pt \parfillskip=0pt
\leftskip=0pt plus 1cm minus 5mm
\rightskip=0pt plus 1cm minus 5mm
For instance, the text in this paragraph is set with some extra |\leftskip|
and |\rightskip| glue, which takes care of centering every line. This
was done as follows:
}
$$
\beginlines
|\setborder[10cm, 1cm, 4mm]\border{|
|\parindent=0pt \parfillskip=0pt|
|\leftskip=0pt plus 1cm minus 5mm \rightskip=0pt plus 1cm minus 5mm|
\goodbreak
|For instance, the text in this paragraph ...|
|...|
\nobreak
|}|
\endlines

\danger If |\setborder| does not suit your purpose, you can write your
own equivalent. Generally, to put text in a border, you first generate
a box containing the border of the appropriate size. Then you make a box
containing this border box plus the text superimposed on it. Superimposing
is done by either ``backspacing'' using negative kerns, or by making a
zero width or height border box, in a similar way as |\llap| makes a zero
width box. Usually, you have to use several nested levels of boxing to
get the desired result.

We have described the different ways of composing border characters, but not
yet how to specify which characters are used. Whenever a border is typeset,
it is assumed that a macro |\borderelm#1| exists. This macro is called with
as argument a number in the range $0,\dots,7$; it should return the appropriate
border element, where the elements are numbered as follows:
\let\borderelm=\numberelm
$$\minusborder{2cm}{5cm}$$
|\borderelm| is called within an hbox; it should typeset a character, a
box, or an vrule. (Since the macro is expanded within an hbox, you should be
careful not to put extra spaces in it; doing that may cause strange
gaps in the border.)

A convenient way of writing |\borderelm| is with
an |\ifcase| construction. For instance, assume that in font |\qc| the
characters |a|, |b|, |c|, etc. correspond to `\roundcorners0',
`\roundcorners1', `\roundcorners2', etc. Then you could write |\borderelm|
as follows:
\beginlines
|\def\borderelm#1%|
\nobreak
|   {{\qc \ifcase#1|
|            a\or b\or c\or d\or e\or f\or g\or h% no extra space|
|         \fi|
|   }}|
\endlines
In fact, a macro like this is already defined in border.tex. It is called
|\roundcorners|, so that you can say |\let\borderelm=\roundcorners| to
get the borders with rounded corners. The corner elements come from
font |\manfnt|, which corresponds to the external font `manfnt.' (The
corner elements are described on page 389 of The \TeX book.) |\roundcorners|
scales, which means that you can say, for instance,
\begintt
\font\manfnt=manfnt scaled 2074
\endtt
to get larger corners --- provided you have the appropriately scaled
font file (2074 corresponds to |\magstep4|).
If you do not want to load the manfnt font (e.g., because your installation
does not have it), you should define |\let\manfnt=\relax| before you
|\input| border.tex.

Hopefully a variety of border fonts will come available in the future. But even
with just the quarter circles you can already vary your borders quite a bit.
We already saw a border with half circles before, it is an easy exercise
to define a complete border that way. The following definition defines
a fancier corner:
\beginlines
|\setbox0=\hbox{\roundcorners2}|
|\vbox{\offinterlineskip|
|      \hbox{\copy0\roundcorners0\copy0}|
|      \hbox to 3\wd0{\hfil\roundcorners7}|
|      \hbox to 3\wd0{\hfil\copy0}|
\nobreak
|     }%|
\endlines
It defines the ``number 2'' (or number 5) corner:
\setbox0=\hbox{\roundcorners2}
\vbox{\offinterlineskip
      \hbox{\copy0\roundcorners0\copy0}
      \hbox to 3\wd0{\hfil\roundcorners7}
      \hbox to 3\wd0{\hfil\copy0}
     } ;
the other corners can be defined similarly.

\danger If you want, you can omit the corners from |\borderelm| (i.e., write
|\borderelm| to return nothing for arguments $0$, $2$, $5$, and $7$).
But if you do not want any edge elements, you should still put something
with width (or height) for the top/bottom (or left/right) edges; for instance,
|\hbox to10pt{}| is a valid top element. Border.tex uses several box and
dimen registers. Rather than reserving private registers, which would
make them unavailable for other purposes, border.tex uses |\box0|, |\box2|,
|\box4|, |\dimen0|, |\dimen2|, and |\count2|. Normally, this does not cause
problems, since they are always restored to their old value. The only time
you should take this into account, is in |\borderelm|: this macro should
not depend on any global values of these registers, nor should it make
any lasting changes to them.

\danger If you are a font designer, and want to define a font that can be
used with border.tex, you should understand something of how |\border| etc.
build the borders. A border is built from three horizontal strips. The top
and bottom strips consist of a corner element, a number of edge elements,
and another corner element. These elements are aligned by their baselines,
and the width of the border(-strip) is determined by the width of the
bounding boxes. Therefore, the ``ink'' in the border elements
should be close to the outside edges of the bounding boxes; otherwise there
will not be a proper relation between the actual size of the border and
the size of the visible border. The center strip is built from an edge,
white space (glue), and another edge. The amount of white space is chosen
so that the width of the center strip is the width of the top strip.
The whole border is built by vertically aligning the top strip, a
number of center strips, and the bottom strip. This is done by aligning
the left hand edges of the horizontal strips. The vertical size of the
border is again determined by the vertical size of the bounding boxes.
You may notice that the quarter circle elements described on p. 389 of The
\TeX book (used in |\roundcorners|), do not fit properly in their bounding
boxes for the purpose of setting borders. In fact, |\roundcorners| must go
to considerable effort to reposition the bounding boxes. If you can, avoid
such problems with any new fonts you design.

There are two more variants of borders. First, to set only one horizontal
strip of a border generated by |\border|, you can use |\hborder|. It takes
four argument: the width, and the numbers of the left element, middle
element, and right element. E.g., |\border{4cm}012| generates the top
of the border, whereas |\border{4cm}567| generates the bottom. There
are also |\hxborder|, |\hminusborder|, and |\hplusborder|. However, there
are no vertical equivalents.

Finally, there are macros |\minusgray| and |\plusgray|. They behave
like their border counterparts, except that the center of the border
is filled with an extra character (|\borderelm8|) rather than with white space.
For use with these macros, |\borderelm| must return characters as follows:
\let\borderelm=\numberelm
$$\minusgray{2cm}{5cm}$$
This is useful if you have characters that contain a ``gray'' pattern
(a ``stipple'' or ``Ben Day'' pattern). Although a font with a gray pattern
should not be hard to define, to the author's knowledge there is currently
no such font in the public domain. These gray macros can also be used with
|\setborder|.

\bye