diff options
author | Karl Berry <karl@freefriends.org> | 2006-01-09 00:56:57 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2006-01-09 00:56:57 +0000 |
commit | f07bb53970ee2ecc53f81a206a3d3a67ef665e4a (patch) | |
tree | 6f57a1d62971db79e5ff023bdfd83b22cb971dc9 /Master/texmf-dist/doc/generic/midnight/border.doc | |
parent | 007f67a693e4d031fd3d792df8e4d5f43e2cb2e7 (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.doc | 372 |
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 + |