% 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