summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/midnight/border.doc
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2006-01-09 00:56:57 +0000
committerKarl Berry <karl@freefriends.org>2006-01-09 00:56:57 +0000
commitf07bb53970ee2ecc53f81a206a3d3a67ef665e4a (patch)
tree6f57a1d62971db79e5ff023bdfd83b22cb971dc9 /Master/texmf-dist/doc/generic/midnight/border.doc
parent007f67a693e4d031fd3d792df8e4d5f43e2cb2e7 (diff)
doc 6
git-svn-id: svn://tug.org/texlive/trunk@85 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/generic/midnight/border.doc')
-rw-r--r--Master/texmf-dist/doc/generic/midnight/border.doc372
1 files changed, 372 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/generic/midnight/border.doc b/Master/texmf-dist/doc/generic/midnight/border.doc
new file mode 100644
index 00000000000..a1ff21f1845
--- /dev/null
+++ b/Master/texmf-dist/doc/generic/midnight/border.doc
@@ -0,0 +1,372 @@
+% 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 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
+