head	1.4;
access;
symbols
	RELENG_8_4:1.4.0.2
	RELENG_9_1_0_RELEASE:1.3.42.1.4.2
	RELENG_9_1:1.3.42.1.0.4
	RELENG_9_1_BP:1.3.42.1
	RELENG_8_3_0_RELEASE:1.3.36.1.8.1
	RELENG_8_3:1.3.36.1.0.8
	RELENG_8_3_BP:1.3.36.1
	RELENG_9_0_0_RELEASE:1.3.42.1.2.1
	RELENG_9_0:1.3.42.1.0.2
	RELENG_9_0_BP:1.3.42.1
	RELENG_9:1.3.0.42
	RELENG_9_BP:1.3
	RELENG_7_4_0_RELEASE:1.3.40.1
	RELENG_8_2_0_RELEASE:1.3.36.1.6.1
	RELENG_7_4:1.3.0.40
	RELENG_7_4_BP:1.3
	RELENG_8_2:1.3.36.1.0.6
	RELENG_8_2_BP:1.3.36.1
	RELENG_8_1_0_RELEASE:1.3.36.1.4.1
	RELENG_8_1:1.3.36.1.0.4
	RELENG_8_1_BP:1.3.36.1
	RELENG_7_3_0_RELEASE:1.3.38.1
	RELENG_7_3:1.3.0.38
	RELENG_7_3_BP:1.3
	RELENG_8_0_0_RELEASE:1.3.36.1.2.1
	RELENG_8_0:1.3.36.1.0.2
	RELENG_8_0_BP:1.3.36.1
	RELENG_8:1.3.0.36
	RELENG_8_BP:1.3
	RELENG_7_2_0_RELEASE:1.3.34.1
	RELENG_7_2:1.3.0.34
	RELENG_7_2_BP:1.3
	RELENG_7_1_0_RELEASE:1.3.32.1
	RELENG_6_4_0_RELEASE:1.3.30.1
	RELENG_7_1:1.3.0.32
	RELENG_7_1_BP:1.3
	RELENG_6_4:1.3.0.30
	RELENG_6_4_BP:1.3
	RELENG_7_0_0_RELEASE:1.3
	RELENG_6_3_0_RELEASE:1.3
	RELENG_7_0:1.3.0.28
	RELENG_7_0_BP:1.3
	RELENG_6_3:1.3.0.26
	RELENG_6_3_BP:1.3
	RELENG_7:1.3.0.24
	RELENG_7_BP:1.3
	RELENG_6_2_0_RELEASE:1.3
	RELENG_6_2:1.3.0.22
	RELENG_6_2_BP:1.3
	RELENG_5_5_0_RELEASE:1.3
	RELENG_5_5:1.3.0.20
	RELENG_5_5_BP:1.3
	RELENG_6_1_0_RELEASE:1.3
	RELENG_6_1:1.3.0.18
	RELENG_6_1_BP:1.3
	RELENG_6_0_0_RELEASE:1.3
	RELENG_6_0:1.3.0.16
	RELENG_6_0_BP:1.3
	RELENG_6:1.3.0.14
	RELENG_6_BP:1.3
	RELENG_5_4_0_RELEASE:1.3
	RELENG_5_4:1.3.0.12
	RELENG_5_4_BP:1.3
	RELENG_5_3_0_RELEASE:1.3
	RELENG_5_3:1.3.0.10
	RELENG_5_3_BP:1.3
	RELENG_5:1.3.0.8
	RELENG_5_BP:1.3
	RELENG_5_2_1_RELEASE:1.3
	RELENG_5_2_0_RELEASE:1.3
	RELENG_5_2:1.3.0.6
	RELENG_5_2_BP:1.3
	RELENG_5_1_0_RELEASE:1.3
	RELENG_5_1:1.3.0.4
	RELENG_5_1_BP:1.3
	RELENG_5_0_0_RELEASE:1.3
	RELENG_5_0:1.3.0.2
	RELENG_5_0_BP:1.3;
locks; strict;
comment	@# @;


1.4
date	2012.11.17.01.50.30;	author svnexp;	state Exp;
branches
	1.4.2.1;
next	1.3;

1.3
date	2002.05.20.13.52.35;	author ru;	state Exp;
branches
	1.3.14.1
	1.3.24.1
	1.3.30.1
	1.3.32.1
	1.3.34.1
	1.3.36.1
	1.3.38.1
	1.3.40.1
	1.3.42.1;
next	1.2;

1.2
date	2002.05.19.04.02.29;	author grog;	state Exp;
branches;
next	1.1;

1.1
date	2002.05.19.03.30.02;	author grog;	state Exp;
branches;
next	;

1.4.2.1
date	2012.11.17.01.50.30;	author svnexp;	state dead;
branches;
next	1.4.2.2;

1.4.2.2
date	2013.03.28.13.03.41;	author svnexp;	state Exp;
branches;
next	;

1.3.14.1
date	2012.11.17.07.41.31;	author svnexp;	state Exp;
branches;
next	;

1.3.24.1
date	2012.11.17.08.03.51;	author svnexp;	state Exp;
branches;
next	;

1.3.30.1
date	2008.10.02.02.57.24;	author kensmith;	state Exp;
branches;
next	;

1.3.32.1
date	2008.11.25.02.59.29;	author kensmith;	state Exp;
branches;
next	;

1.3.34.1
date	2009.04.15.03.14.26;	author kensmith;	state Exp;
branches;
next	;

1.3.36.1
date	2009.08.03.08.13.06;	author kensmith;	state Exp;
branches
	1.3.36.1.2.1
	1.3.36.1.4.1
	1.3.36.1.6.1
	1.3.36.1.8.1;
next	1.3.36.2;

1.3.36.2
date	2012.11.17.10.36.18;	author svnexp;	state Exp;
branches;
next	;

1.3.36.1.2.1
date	2009.10.25.01.10.29;	author kensmith;	state Exp;
branches;
next	;

1.3.36.1.4.1
date	2010.06.14.02.09.06;	author kensmith;	state Exp;
branches;
next	;

1.3.36.1.6.1
date	2010.12.21.17.09.25;	author kensmith;	state Exp;
branches;
next	;

1.3.36.1.8.1
date	2012.03.03.06.15.13;	author kensmith;	state Exp;
branches;
next	1.3.36.1.8.2;

1.3.36.1.8.2
date	2012.11.17.08.24.58;	author svnexp;	state Exp;
branches;
next	;

1.3.38.1
date	2010.02.10.00.26.20;	author kensmith;	state Exp;
branches;
next	;

1.3.40.1
date	2010.12.21.17.10.29;	author kensmith;	state Exp;
branches;
next	1.3.40.2;

1.3.40.2
date	2012.11.17.08.16.56;	author svnexp;	state Exp;
branches;
next	;

1.3.42.1
date	2011.09.23.00.51.37;	author kensmith;	state Exp;
branches
	1.3.42.1.2.1
	1.3.42.1.4.1;
next	1.3.42.2;

1.3.42.2
date	2012.11.17.11.36.35;	author svnexp;	state Exp;
branches;
next	;

1.3.42.1.2.1
date	2011.11.11.04.20.22;	author kensmith;	state Exp;
branches;
next	1.3.42.1.2.2;

1.3.42.1.2.2
date	2012.11.17.08.36.34;	author svnexp;	state Exp;
branches;
next	;

1.3.42.1.4.1
date	2012.08.05.23.54.33;	author kensmith;	state Exp;
branches;
next	1.3.42.1.4.2;

1.3.42.1.4.2
date	2012.11.17.08.47.24;	author svnexp;	state Exp;
branches;
next	;


desc
@@


1.4
log
@Switching exporter and resync
@
text
@.\" Copyright (C) Caldera International Inc. 2001-2002.  All rights reserved.
.\" 
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions are
.\" met:
.\" 
.\" Redistributions of source code and documentation must retain the above
.\" copyright notice, this list of conditions and the following
.\" disclaimer.
.\" 
.\" Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\" 
.\" All advertising materials mentioning features or use of this software
.\" must display the following acknowledgement:
.\" 
.\" This product includes software developed or owned by Caldera
.\" International, Inc.  Neither the name of Caldera International, Inc.
.\" nor the names of other contributors may be used to endorse or promote
.\" products derived from this software without specific prior written
.\" permission.
.\" 
.\" USE OF THE SOFTWARE PROVIDED FOR UNDER THIS LICENSE BY CALDERA
.\" INTERNATIONAL, INC.  AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
.\" DISCLAIMED.  IN NO EVENT SHALL CALDERA INTERNATIONAL, INC. BE LIABLE
.\" FOR ANY DIRECT, INDIRECT INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
.\" OR OTHERWISE) RISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
.\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.\"	@@(#)m5	8.1 (Berkeley) 8/14/93
.\"
.\" $FreeBSD: head/share/doc/usd/21.troff/m5 96992 2002-05-20 13:52:35Z ru $
.ds H T
.tr |
.tr ~|
.de x1
.xx
.ft B
.in .2i
.nf
.ne 2.1
.ta 1i
..
.de x2
.fi
.in 0
.ft R
.xx
..
.br
.ce
.ft B
.rs
.sp 0.5i
TUTORIAL EXAMPLES
.ft R
.sp 2
.nr p 0
.2C
.ns
.mh
.mk
Introduction
.pg
Although \*(NR and \*(TR
have by design a syntax reminiscent
of earlier text processors*
.fn
.xx
*For example:
P.|A.|Crisman, Ed.,
.ul
The Compatible Time-Sharing System,
MIT Press, 1965, Section|AH9.01
(Description of RUNOFF program on MIT's CTSS system).
.ef
with the intent of easing their use,
it is almost always necessary to
prepare at least a small set of macro definitions
to describe most documents.
Such common formatting needs
as page margins and footnotes
are deliberately not built into \*(NR and \*(TR.
Instead,
the macro and string definition, number register, diversion,
environment switching, page-position trap, and conditional input mechanisms
provide the basis for user-defined implementations.
.pg
The examples to be discussed are intended to be useful and somewhat realistic,
but won't necessarily cover all relevant contingencies.
Explicit numerical parameters are used
in the examples
to make them easier to read and to
illustrate typical values.
In many cases, number registers would really be used
to reduce the number of places where numerical
information is kept,
and to concentrate conditional parameter initialization
like that which depends on whether \*(TR or \*(NR is being used.
.mh
Page Margins
.pg
As discussed in \(sc3,
\fIheader\fR and \fIfooter\fR macros are usually defined
to describe the top and bottom page margin areas respectively.
A trap is planted at page position 0 for the header, and at
\fI\-N\fR (\fIN\fR from the page bottom) for the footer.
The simplest such definitions might be
.x1
&de hd	\e"define header
\'sp 1i
&&	\e"end definition
&de fo	\e"define footer
\'bp
&&	\e"end definition
&wh 0 hd
&wh \-1i fo
.x2
which provide blank 1|inch top and bottom margins.
The header will occur on the \fIfirst\fR page,
only if the definition and trap exist prior to
the initial pseudo-page transition (\(sc3).
In fill mode, the output line that springs the footer trap
was typically forced out because some part or whole word didn't fit on it.
If anything in the footer and header that follows causes a \fIbreak\fR,
that word or part word will be forced out.
In this and other examples,
requests like \fBbp\fR and \fBsp\fR that normally cause breaks are invoked using
the \fIno-break\fR control character \fB\'\fR
to avoid this.
When the header\(slfooter design contains material
requiring independent text processing, the
environment may be switched, avoiding
most interaction with the running text.
.pg
A more realistic example would be
.x1
&de hd	\e"header
&if t .tl \'\|\e(rn\'\'\e(rn\'  \e"troff cut mark
&if \e\en%>1 \e{\e
\'sp ~\|0.5i\-1	\e"tl base at 0.5i
&tl \'\'\- % \-\'\'	\e"centered page number
&ps	\e"restore size
&ft	\e"restore font
&vs  \e}	\e"restore vs
\'sp ~\|1.0i  	\e"space to 1.0i
&ns	\e"turn on no-space mode
&&
&de fo	\e"footer
&ps 10	\e"set footer\(slheader size
&ft R	\e"set font
&vs 12p	\e"set base-line spacing
&if \e\en%=1 \e{\e
\'sp ~\|\e\en(.pu\-0.5i\-1  \e"tl base 0.5i up
&tl \'\'\- % \-\'\' \e}  \e"first page number
\'bp
&&
&wh 0 hd
&wh \-1i fo
.x2
which sets the size, font, and base-line spacing for the
header\(slfooter material, and ultimately restores them.
The material in this case is a page number at the bottom of the
first page and at the top of the remaining pages.
If \*(TR is used, a \fIcut mark\fR is drawn in the form
of \fIroot-en\fR's at each margin.
The \fBsp\fR's refer to absolute positions to avoid
dependence on the base-line spacing.
Another reason for this in the footer
is that the footer is invoked by printing a line whose
vertical spacing swept past the trap position by possibly
as much as the base-line spacing.
The \fIno-space\fR mode is turned on at the end of \fBhd\fR
to render ineffective
accidental occurrences of \fBsp\fR at the top of the running text.
.pg
The above method of restoring size, font, etc. presupposes
that such requests (that set \fIprevious\fR value) are \fInot\fR
used in the running text.
A better scheme is save and restore both the current \fIand\fR
previous values as shown for size in the following:
.x1
&de fo
&nr s1 \e\en(.s	\e"current size
&ps
&nr s2 \e\en(.s	\e"previous size
&  ---	\e"rest of footer
&&
&de hd
&  ---	\e"header stuff
&ps \e\en(s2	\e"restore previous size
&ps \e\en(s1	\e"restore current size
&&
.x2
Page numbers may be printed in the bottom margin
by a separate macro triggered during the footer's
page ejection:
.x1
&de bn	\e"bottom number
&tl \'\'\- % \-\'\'	\e"centered page number
&&
&wh \-0.5i\-1v bn	 \e"tl base 0.5i up
.x2
.mh
Paragraphs and Headings
.pg
The housekeeping
associated with starting a new paragraph should be collected
in a paragraph macro
that, for example,
does the desired preparagraph spacing,
forces the correct font, size, base-line spacing, and indent,
checks that enough space remains for \fImore than one\fR line,
and
requests a temporary indent.
.x1
&de pg	\e"paragraph
&br	\e"break
&ft R	\e"force font,
&ps 10	\e"size,
&vs 12p	\e"spacing,
&in 0	\e"and indent
&sp 0.4	\e"prespace
&ne 1+\e\en(.Vu	\e"want more than 1 line
&ti 0.2i	\e"temp indent
&&
.x2
The first break in \fBpg\fR
will force out any previous partial lines,
and must occur before the \fBvs\fR.
The forcing of font, etc. is
partly a defense against prior error and
partly to permit
things like section heading macros to
set parameters only once.
The prespacing parameter is suitable for \*(TR;
a larger space, at least as big as the output device vertical resolution, would be
more suitable in \*(NR.
The choice of remaining space to test for in the \fBne\fR
is the smallest amount greater than one line
(the \fB.V\fR is the available vertical resolution).
.pg
A macro to automatically number section headings
might look like:
.x1
&de sc	\e"section
&  ---	\e"force font, etc.
&sp 0.4	\e"prespace
&ne 2.4+\e\en(.Vu \e"want 2.4+ lines
.lg 0
&fi
.lg
\e\en+S.
&&
&nr S 0 1	\e"init S
.x2
The usage is \fB.sc\fR,
followed by the section heading text,
followed by \fB.pg\fR.
The \fBne\fR test value includes one line of heading,
0.4 line in the following \fBpg\fR, and
one line of the paragraph text.
A word consisting of the next section number and a period is
produced to begin the heading line.
The format of the number may be set by \fBaf\fR (\(sc8).
.pg
Another common form is the labeled, indented paragraph,
where the label protrudes left into the indent space.
.x1
&de lp	\e"labeled paragraph
&pg
&in 0.5i	\e"paragraph indent
&ta 0.2i 0.5i	\e"label, paragraph
&ti 0
\et\e\e$1\et\ec	\e"flow into paragraph
&&
.x2
The intended usage is "\fB.lp\fR \fIlabel\fR\|";
\fIlabel\fR will begin at 0.2\|inch, and
cannot exceed a length of 0.3\|inch without intruding into
the paragraph.
The label could be right adjusted against 0.4\|inch by
setting the tabs instead with \fB.ta|0.4iR|0.5i\fR.
The last line of \fBlp\fR ends with \fB\ec\fR so that
it will become a part of the first line of the text
that follows.
.mh
Multiple Column Output
.pg
The production of multiple column pages requires
the footer macro to decide whether it was
invoked by other than the last column,
so that it will begin a new column rather than
produce the bottom margin.
The header can initialize a column register that
the footer will increment and test.
The following is arranged for two columns, but
is easily modified for more.
.x1
&de hd	\e"header
&  ---
&nr cl 0 1	\e"init column count
&mk	\e"mark top of text
&&
&de fo	\e"footer
&ie \e\en+(cl<2 \e{\e
&po +3.4i	\e"next column; 3.1+0.3
&rt	\e"back to mark
&ns \e}	\e"no-space mode
&el \e{\e
&po \e\enMu	\e"restore left margin
&  ---
\'bp \e}
&&
&ll 3.1i	\e"column width
&nr M \e\en(.o	\e"save left margin
.x2
Typically a portion of the top of the first page
contains full width text;
the request for the narrower line length,
as well as another \fB.mk\fR would
be made where the two column output was to begin.
.mh
Footnote Processing
.pg
The footnote mechanism to be described is used by
imbedding the footnotes in the input text at the
point of reference,
demarcated by an initial \fB.fn\fR and a terminal \fB.ef\fR:
.x1
&fn
\fIFootnote text and control lines...\fP
&ef
.x2
In the following,
footnotes are processed in a separate environment and diverted
for later printing in the space immediately prior to the bottom
margin.
There is provision for the case where the last collected
footnote doesn't completely fit in the available space.
.x1
&de hd	\e"header
&  ---
&nr x 0 1	\e"init footnote count
&nr y 0\-\e\enb	\e"current footer place
&ch fo \-\e\enbu	\e"reset footer trap
&if \e\en(dn .fz	\e"leftover footnote
&&
&de fo	\e"footer
&nr dn 0	\e"zero last diversion size
&if \e\enx \e{\e
&ev 1	\e"expand footnotes in ev1
&nf	\e"retain vertical size
&FN	\e"footnotes
&rm FN	\e"delete it
&if "\e\en(.z"fy" .di	 \e"end overflow diversion
&nr x 0	\e"disable fx
&ev  \e}	\e"pop environment
&  ---
\'bp
&&
&de fx	\e"process footnote overflow
&if \e\enx .di fy	\e"divert overflow
&&
&de fn	\e"start footnote
&da FN	\e"divert (append) footnote
&ev 1	\e"in environment 1
&if \e\en+x=1 .fs	 \e"if first, include separator
.lg 0
&fi	\e"fill mode
.lg
&&
&de ef	\e"end footnote
&br	\e"finish output
&nr z \e\en(.v	\e"save spacing
&ev	\e"pop ev
&di	\e"end diversion
&nr y \-\e\en(dn	\e"new footer position,
&if \e\enx=1 .nr y \-(\e\en(.v\-\e\enz) \e
	\e"uncertainty correction
&ch fo \e\enyu	\e"y is negative
&if (\|\e\en(nl+1v)>(\|\e\en(.p+\e\eny) \e
&ch fo \e\en(nlu+1v	 \e"it didn't fit
&&
&de fs	\e"separator
\el\'\|1i\'	\e"1 inch rule
&br
&&
&de fz	\e"get leftover footnote
&fn
&nf	\e"retain vertical size
&fy	\e"where fx put it
&ef
&&
&nr b 1.0i	\e"bottom margin size
&wh 0 hd	\e"header trap
&wh 12i fo	\e"footer trap, temp position
&wh \-\e\enbu fx	\e"fx at footer position
&ch fo \-\e\enbu	\e"conceal fx with fo
.x2
The header \fBhd\fR initializes a footnote count register \fBx\fR,
and sets both the current footer trap position register \fBy\fR and
the footer trap itself to a nominal position specified in
register \fBb\fR.
In addition, if the register \fBdn\fR indicates a leftover footnote,
\fBfz\fR is invoked to reprocess it.
The footnote start macro \fBfn\fR begins a diversion (append) in environment 1,
and increments the count \fBx\fR; if the count is one, the footnote separator \fBfs\fR
is interpolated.
The separator is kept in a separate macro to permit user redefinition.
The footnote end macro \fBef\fR restores
the previous environment and ends the diversion after saving the spacing size in register \fBz\fR.
\fBy\fR is then decremented by the size of the footnote, available in \fBdn\fR;
then on the first footnote, \fBy\fR is further decremented by the difference
in vertical base-line spacings of the two environments, to
prevent the late triggering the footer trap from causing the last
line of the combined footnotes to overflow.
The footer trap is then set to the lower (on the page) of \fBy\fR or the current page position (\fBnl\fR)
plus one line, to allow for printing the reference line.
If indicated by \fBx\fR, the footer \fBfo\fR rereads the footnotes from \fBFN\fR in nofill mode
in environment 1,
and deletes \fBFN\fR.
If the footnotes were too large to fit, the macro \fBfx\fR will be trap-invoked to redivert
the overflow into \fBfy\fR,
and the register \fBdn\fR will later indicate to the header whether \fBfy\fR is empty.
Both \fBfo\fR and \fBfx\fR are planted in the nominal footer trap position in an order
that causes \fBfx\fR to be concealed unless the \fBfo\fR trap is moved.
The footer then terminates the overflow diversion, if necessary, and
zeros \fBx\fR to disable \fBfx\fR,
because the uncertainty correction
together with a not-too-late triggering of the footer can result
in the footnote rereading finishing before reaching the \fBfx\fR trap.
.pg
A good exercise for the student is to combine the multiple-column and footnote mechanisms.
.mh
The Last Page
.pg
After the last input file has ended, \*(NR and \*(TR
invoke the \fIend macro\fR (\(sc7), if any,
and when it finishes, eject the remainder of the page.
During the eject, any traps encountered are processed normally.
At the \fIend\fR of this last page, processing terminates
\fIunless\fR a partial line, word, or partial word remains.
If it is desired that another page be started, the end-macro
.x1
&de en	\e"end-macro
\ec
\'bp
&&
&em en
.x2
will deposit a null partial word,
and effect another last page.
.1C
'bp
@


1.4.2.1
log
@file m5 was added on branch RELENG_8_4 on 2013-03-28 13:03:41 +0000
@
text
@d1 462
@


1.4.2.2
log
@## SVN ## Exported commit - http://svnweb.freebsd.org/changeset/base/248810
## SVN ## CVS IS DEPRECATED: http://wiki.freebsd.org/CvsIsDeprecated
@
text
@a0 462
.\" Copyright (C) Caldera International Inc. 2001-2002.  All rights reserved.
.\" 
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions are
.\" met:
.\" 
.\" Redistributions of source code and documentation must retain the above
.\" copyright notice, this list of conditions and the following
.\" disclaimer.
.\" 
.\" Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\" 
.\" All advertising materials mentioning features or use of this software
.\" must display the following acknowledgement:
.\" 
.\" This product includes software developed or owned by Caldera
.\" International, Inc.  Neither the name of Caldera International, Inc.
.\" nor the names of other contributors may be used to endorse or promote
.\" products derived from this software without specific prior written
.\" permission.
.\" 
.\" USE OF THE SOFTWARE PROVIDED FOR UNDER THIS LICENSE BY CALDERA
.\" INTERNATIONAL, INC.  AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
.\" DISCLAIMED.  IN NO EVENT SHALL CALDERA INTERNATIONAL, INC. BE LIABLE
.\" FOR ANY DIRECT, INDIRECT INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
.\" OR OTHERWISE) RISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
.\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.\"	@@(#)m5	8.1 (Berkeley) 8/14/93
.\"
.\" $FreeBSD: releng/8.4/share/doc/usd/21.troff/m5 96992 2002-05-20 13:52:35Z ru $
.ds H T
.tr |
.tr ~|
.de x1
.xx
.ft B
.in .2i
.nf
.ne 2.1
.ta 1i
..
.de x2
.fi
.in 0
.ft R
.xx
..
.br
.ce
.ft B
.rs
.sp 0.5i
TUTORIAL EXAMPLES
.ft R
.sp 2
.nr p 0
.2C
.ns
.mh
.mk
Introduction
.pg
Although \*(NR and \*(TR
have by design a syntax reminiscent
of earlier text processors*
.fn
.xx
*For example:
P.|A.|Crisman, Ed.,
.ul
The Compatible Time-Sharing System,
MIT Press, 1965, Section|AH9.01
(Description of RUNOFF program on MIT's CTSS system).
.ef
with the intent of easing their use,
it is almost always necessary to
prepare at least a small set of macro definitions
to describe most documents.
Such common formatting needs
as page margins and footnotes
are deliberately not built into \*(NR and \*(TR.
Instead,
the macro and string definition, number register, diversion,
environment switching, page-position trap, and conditional input mechanisms
provide the basis for user-defined implementations.
.pg
The examples to be discussed are intended to be useful and somewhat realistic,
but won't necessarily cover all relevant contingencies.
Explicit numerical parameters are used
in the examples
to make them easier to read and to
illustrate typical values.
In many cases, number registers would really be used
to reduce the number of places where numerical
information is kept,
and to concentrate conditional parameter initialization
like that which depends on whether \*(TR or \*(NR is being used.
.mh
Page Margins
.pg
As discussed in \(sc3,
\fIheader\fR and \fIfooter\fR macros are usually defined
to describe the top and bottom page margin areas respectively.
A trap is planted at page position 0 for the header, and at
\fI\-N\fR (\fIN\fR from the page bottom) for the footer.
The simplest such definitions might be
.x1
&de hd	\e"define header
\'sp 1i
&&	\e"end definition
&de fo	\e"define footer
\'bp
&&	\e"end definition
&wh 0 hd
&wh \-1i fo
.x2
which provide blank 1|inch top and bottom margins.
The header will occur on the \fIfirst\fR page,
only if the definition and trap exist prior to
the initial pseudo-page transition (\(sc3).
In fill mode, the output line that springs the footer trap
was typically forced out because some part or whole word didn't fit on it.
If anything in the footer and header that follows causes a \fIbreak\fR,
that word or part word will be forced out.
In this and other examples,
requests like \fBbp\fR and \fBsp\fR that normally cause breaks are invoked using
the \fIno-break\fR control character \fB\'\fR
to avoid this.
When the header\(slfooter design contains material
requiring independent text processing, the
environment may be switched, avoiding
most interaction with the running text.
.pg
A more realistic example would be
.x1
&de hd	\e"header
&if t .tl \'\|\e(rn\'\'\e(rn\'  \e"troff cut mark
&if \e\en%>1 \e{\e
\'sp ~\|0.5i\-1	\e"tl base at 0.5i
&tl \'\'\- % \-\'\'	\e"centered page number
&ps	\e"restore size
&ft	\e"restore font
&vs  \e}	\e"restore vs
\'sp ~\|1.0i  	\e"space to 1.0i
&ns	\e"turn on no-space mode
&&
&de fo	\e"footer
&ps 10	\e"set footer\(slheader size
&ft R	\e"set font
&vs 12p	\e"set base-line spacing
&if \e\en%=1 \e{\e
\'sp ~\|\e\en(.pu\-0.5i\-1  \e"tl base 0.5i up
&tl \'\'\- % \-\'\' \e}  \e"first page number
\'bp
&&
&wh 0 hd
&wh \-1i fo
.x2
which sets the size, font, and base-line spacing for the
header\(slfooter material, and ultimately restores them.
The material in this case is a page number at the bottom of the
first page and at the top of the remaining pages.
If \*(TR is used, a \fIcut mark\fR is drawn in the form
of \fIroot-en\fR's at each margin.
The \fBsp\fR's refer to absolute positions to avoid
dependence on the base-line spacing.
Another reason for this in the footer
is that the footer is invoked by printing a line whose
vertical spacing swept past the trap position by possibly
as much as the base-line spacing.
The \fIno-space\fR mode is turned on at the end of \fBhd\fR
to render ineffective
accidental occurrences of \fBsp\fR at the top of the running text.
.pg
The above method of restoring size, font, etc. presupposes
that such requests (that set \fIprevious\fR value) are \fInot\fR
used in the running text.
A better scheme is save and restore both the current \fIand\fR
previous values as shown for size in the following:
.x1
&de fo
&nr s1 \e\en(.s	\e"current size
&ps
&nr s2 \e\en(.s	\e"previous size
&  ---	\e"rest of footer
&&
&de hd
&  ---	\e"header stuff
&ps \e\en(s2	\e"restore previous size
&ps \e\en(s1	\e"restore current size
&&
.x2
Page numbers may be printed in the bottom margin
by a separate macro triggered during the footer's
page ejection:
.x1
&de bn	\e"bottom number
&tl \'\'\- % \-\'\'	\e"centered page number
&&
&wh \-0.5i\-1v bn	 \e"tl base 0.5i up
.x2
.mh
Paragraphs and Headings
.pg
The housekeeping
associated with starting a new paragraph should be collected
in a paragraph macro
that, for example,
does the desired preparagraph spacing,
forces the correct font, size, base-line spacing, and indent,
checks that enough space remains for \fImore than one\fR line,
and
requests a temporary indent.
.x1
&de pg	\e"paragraph
&br	\e"break
&ft R	\e"force font,
&ps 10	\e"size,
&vs 12p	\e"spacing,
&in 0	\e"and indent
&sp 0.4	\e"prespace
&ne 1+\e\en(.Vu	\e"want more than 1 line
&ti 0.2i	\e"temp indent
&&
.x2
The first break in \fBpg\fR
will force out any previous partial lines,
and must occur before the \fBvs\fR.
The forcing of font, etc. is
partly a defense against prior error and
partly to permit
things like section heading macros to
set parameters only once.
The prespacing parameter is suitable for \*(TR;
a larger space, at least as big as the output device vertical resolution, would be
more suitable in \*(NR.
The choice of remaining space to test for in the \fBne\fR
is the smallest amount greater than one line
(the \fB.V\fR is the available vertical resolution).
.pg
A macro to automatically number section headings
might look like:
.x1
&de sc	\e"section
&  ---	\e"force font, etc.
&sp 0.4	\e"prespace
&ne 2.4+\e\en(.Vu \e"want 2.4+ lines
.lg 0
&fi
.lg
\e\en+S.
&&
&nr S 0 1	\e"init S
.x2
The usage is \fB.sc\fR,
followed by the section heading text,
followed by \fB.pg\fR.
The \fBne\fR test value includes one line of heading,
0.4 line in the following \fBpg\fR, and
one line of the paragraph text.
A word consisting of the next section number and a period is
produced to begin the heading line.
The format of the number may be set by \fBaf\fR (\(sc8).
.pg
Another common form is the labeled, indented paragraph,
where the label protrudes left into the indent space.
.x1
&de lp	\e"labeled paragraph
&pg
&in 0.5i	\e"paragraph indent
&ta 0.2i 0.5i	\e"label, paragraph
&ti 0
\et\e\e$1\et\ec	\e"flow into paragraph
&&
.x2
The intended usage is "\fB.lp\fR \fIlabel\fR\|";
\fIlabel\fR will begin at 0.2\|inch, and
cannot exceed a length of 0.3\|inch without intruding into
the paragraph.
The label could be right adjusted against 0.4\|inch by
setting the tabs instead with \fB.ta|0.4iR|0.5i\fR.
The last line of \fBlp\fR ends with \fB\ec\fR so that
it will become a part of the first line of the text
that follows.
.mh
Multiple Column Output
.pg
The production of multiple column pages requires
the footer macro to decide whether it was
invoked by other than the last column,
so that it will begin a new column rather than
produce the bottom margin.
The header can initialize a column register that
the footer will increment and test.
The following is arranged for two columns, but
is easily modified for more.
.x1
&de hd	\e"header
&  ---
&nr cl 0 1	\e"init column count
&mk	\e"mark top of text
&&
&de fo	\e"footer
&ie \e\en+(cl<2 \e{\e
&po +3.4i	\e"next column; 3.1+0.3
&rt	\e"back to mark
&ns \e}	\e"no-space mode
&el \e{\e
&po \e\enMu	\e"restore left margin
&  ---
\'bp \e}
&&
&ll 3.1i	\e"column width
&nr M \e\en(.o	\e"save left margin
.x2
Typically a portion of the top of the first page
contains full width text;
the request for the narrower line length,
as well as another \fB.mk\fR would
be made where the two column output was to begin.
.mh
Footnote Processing
.pg
The footnote mechanism to be described is used by
imbedding the footnotes in the input text at the
point of reference,
demarcated by an initial \fB.fn\fR and a terminal \fB.ef\fR:
.x1
&fn
\fIFootnote text and control lines...\fP
&ef
.x2
In the following,
footnotes are processed in a separate environment and diverted
for later printing in the space immediately prior to the bottom
margin.
There is provision for the case where the last collected
footnote doesn't completely fit in the available space.
.x1
&de hd	\e"header
&  ---
&nr x 0 1	\e"init footnote count
&nr y 0\-\e\enb	\e"current footer place
&ch fo \-\e\enbu	\e"reset footer trap
&if \e\en(dn .fz	\e"leftover footnote
&&
&de fo	\e"footer
&nr dn 0	\e"zero last diversion size
&if \e\enx \e{\e
&ev 1	\e"expand footnotes in ev1
&nf	\e"retain vertical size
&FN	\e"footnotes
&rm FN	\e"delete it
&if "\e\en(.z"fy" .di	 \e"end overflow diversion
&nr x 0	\e"disable fx
&ev  \e}	\e"pop environment
&  ---
\'bp
&&
&de fx	\e"process footnote overflow
&if \e\enx .di fy	\e"divert overflow
&&
&de fn	\e"start footnote
&da FN	\e"divert (append) footnote
&ev 1	\e"in environment 1
&if \e\en+x=1 .fs	 \e"if first, include separator
.lg 0
&fi	\e"fill mode
.lg
&&
&de ef	\e"end footnote
&br	\e"finish output
&nr z \e\en(.v	\e"save spacing
&ev	\e"pop ev
&di	\e"end diversion
&nr y \-\e\en(dn	\e"new footer position,
&if \e\enx=1 .nr y \-(\e\en(.v\-\e\enz) \e
	\e"uncertainty correction
&ch fo \e\enyu	\e"y is negative
&if (\|\e\en(nl+1v)>(\|\e\en(.p+\e\eny) \e
&ch fo \e\en(nlu+1v	 \e"it didn't fit
&&
&de fs	\e"separator
\el\'\|1i\'	\e"1 inch rule
&br
&&
&de fz	\e"get leftover footnote
&fn
&nf	\e"retain vertical size
&fy	\e"where fx put it
&ef
&&
&nr b 1.0i	\e"bottom margin size
&wh 0 hd	\e"header trap
&wh 12i fo	\e"footer trap, temp position
&wh \-\e\enbu fx	\e"fx at footer position
&ch fo \-\e\enbu	\e"conceal fx with fo
.x2
The header \fBhd\fR initializes a footnote count register \fBx\fR,
and sets both the current footer trap position register \fBy\fR and
the footer trap itself to a nominal position specified in
register \fBb\fR.
In addition, if the register \fBdn\fR indicates a leftover footnote,
\fBfz\fR is invoked to reprocess it.
The footnote start macro \fBfn\fR begins a diversion (append) in environment 1,
and increments the count \fBx\fR; if the count is one, the footnote separator \fBfs\fR
is interpolated.
The separator is kept in a separate macro to permit user redefinition.
The footnote end macro \fBef\fR restores
the previous environment and ends the diversion after saving the spacing size in register \fBz\fR.
\fBy\fR is then decremented by the size of the footnote, available in \fBdn\fR;
then on the first footnote, \fBy\fR is further decremented by the difference
in vertical base-line spacings of the two environments, to
prevent the late triggering the footer trap from causing the last
line of the combined footnotes to overflow.
The footer trap is then set to the lower (on the page) of \fBy\fR or the current page position (\fBnl\fR)
plus one line, to allow for printing the reference line.
If indicated by \fBx\fR, the footer \fBfo\fR rereads the footnotes from \fBFN\fR in nofill mode
in environment 1,
and deletes \fBFN\fR.
If the footnotes were too large to fit, the macro \fBfx\fR will be trap-invoked to redivert
the overflow into \fBfy\fR,
and the register \fBdn\fR will later indicate to the header whether \fBfy\fR is empty.
Both \fBfo\fR and \fBfx\fR are planted in the nominal footer trap position in an order
that causes \fBfx\fR to be concealed unless the \fBfo\fR trap is moved.
The footer then terminates the overflow diversion, if necessary, and
zeros \fBx\fR to disable \fBfx\fR,
because the uncertainty correction
together with a not-too-late triggering of the footer can result
in the footnote rereading finishing before reaching the \fBfx\fR trap.
.pg
A good exercise for the student is to combine the multiple-column and footnote mechanisms.
.mh
The Last Page
.pg
After the last input file has ended, \*(NR and \*(TR
invoke the \fIend macro\fR (\(sc7), if any,
and when it finishes, eject the remainder of the page.
During the eject, any traps encountered are processed normally.
At the \fIend\fR of this last page, processing terminates
\fIunless\fR a partial line, word, or partial word remains.
If it is desired that another page be started, the end-macro
.x1
&de en	\e"end-macro
\ec
\'bp
&&
&em en
.x2
will deposit a null partial word,
and effect another last page.
.1C
'bp
@


1.3
log
@Fixed roffing.
@
text
@d39 1
a39 1
.\" $FreeBSD$
@


1.3.24.1
log
@Switch importer
@
text
@d39 1
a39 1
.\" $FreeBSD: stable/7/share/doc/usd/21.troff/m5 96992 2002-05-20 13:52:35Z ru $
@


1.3.14.1
log
@Switch importer
@
text
@d39 1
a39 1
.\" $FreeBSD: stable/6/share/doc/usd/21.troff/m5 96992 2002-05-20 13:52:35Z ru $
@


1.3.42.1
log
@SVN rev 225736 on 2011-09-23 00:51:37Z by kensmith

Copy head to stable/9 as part of 9.0-RELEASE release cycle.

Approved by:	re (implicit)
@
text
@@


1.3.42.2
log
@## SVN ##
## SVN ## Exported commit - http://svnweb.freebsd.org/changeset/base/ 242902
## SVN ## CVS IS DEPRECATED: http://wiki.freebsd.org/CvsIsDeprecated
## SVN ##
## SVN ## ------------------------------------------------------------------------
## SVN ## r242902 | dteske | 2012-11-11 23:29:45 +0000 (Sun, 11 Nov 2012) | 10 lines
## SVN ##
## SVN ## Fix a regression introduced by SVN r211417 that saw the breakage of a feature
## SVN ## documented in usr.sbin/sysinstall/help/shortcuts.hlp (reproduced below):
## SVN ##
## SVN ## If /usr/sbin/sysinstall is linked to another filename, say
## SVN ## `/usr/local/bin/configPackages', then the basename will be used
## SVN ## as an implicit command name.
## SVN ##
## SVN ## Reviewed by:	adrian (co-mentor)
## SVN ## Approved by:	adrian (co-mentor)
## SVN ##
## SVN ## ------------------------------------------------------------------------
## SVN ##
@
text
@d39 1
a39 1
.\" $FreeBSD: stable/9/share/doc/usd/21.troff/m5 96992 2002-05-20 13:52:35Z ru $
@


1.3.42.1.4.1
log
@SVN rev 239080 on 2012-08-05 23:54:33Z by kensmith

Copy stable/9 to releng/9.1 as part of the 9.1-RELEASE release process.

Approved by:	re (implicit)
@
text
@@


1.3.42.1.4.2
log
@Switch importer
@
text
@d39 1
a39 1
.\" $FreeBSD: releng/9.1/share/doc/usd/21.troff/m5 96992 2002-05-20 13:52:35Z ru $
@


1.3.42.1.2.1
log
@SVN rev 227445 on 2011-11-11 04:20:22Z by kensmith

Copy stable/9 to releng/9.0 as part of the FreeBSD 9.0-RELEASE release
cycle.

Approved by:	re (implicit)
@
text
@@


1.3.42.1.2.2
log
@Switch importer
@
text
@d39 1
a39 1
.\" $FreeBSD: releng/9.0/share/doc/usd/21.troff/m5 96992 2002-05-20 13:52:35Z ru $
@


1.3.40.1
log
@SVN rev 216618 on 2010-12-21 17:10:29Z by kensmith

Copy stable/7 to releng/7.4 in preparation for FreeBSD-7.4 release.

Approved by:	re (implicit)
@
text
@@


1.3.40.2
log
@Switch importer
@
text
@d39 1
a39 1
.\" $FreeBSD: releng/7.4/share/doc/usd/21.troff/m5 96992 2002-05-20 13:52:35Z ru $
@


1.3.38.1
log
@SVN rev 203736 on 2010-02-10 00:26:20Z by kensmith

Copy stable/7 to releng/7.3 as part of the 7.3-RELEASE process.

Approved by:	re (implicit)
@
text
@@


1.3.36.1
log
@SVN rev 196045 on 2009-08-03 08:13:06Z by kensmith

Copy head to stable/8 as part of 8.0 Release cycle.

Approved by:	re (Implicit)
@
text
@@


1.3.36.2
log
@## SVN ##
## SVN ## Exported commit - http://svnweb.freebsd.org/changeset/base/ 242909
## SVN ## CVS IS DEPRECATED: http://wiki.freebsd.org/CvsIsDeprecated
## SVN ##
## SVN ## ------------------------------------------------------------------------
## SVN ## r242909 | dim | 2012-11-12 07:47:19 +0000 (Mon, 12 Nov 2012) | 20 lines
## SVN ##
## SVN ## MFC r242625:
## SVN ##
## SVN ## Remove duplicate const specifiers in many drivers (I hope I got all of
## SVN ## them, please let me know if not).  Most of these are of the form:
## SVN ##
## SVN ## static const struct bzzt_type {
## SVN ##       [...list of members...]
## SVN ## } const bzzt_devs[] = {
## SVN ##       [...list of initializers...]
## SVN ## };
## SVN ##
## SVN ## The second const is unnecessary, as arrays cannot be modified anyway,
## SVN ## and if the elements are const, the whole thing is const automatically
## SVN ## (e.g. it is placed in .rodata).
## SVN ##
## SVN ## I have verified this does not change the binary output of a full kernel
## SVN ## build (except for build timestamps embedded in the object files).
## SVN ##
## SVN ## Reviewed by:	yongari, marius
## SVN ##
## SVN ## ------------------------------------------------------------------------
## SVN ##
@
text
@d39 1
a39 1
.\" $FreeBSD: stable/8/share/doc/usd/21.troff/m5 96992 2002-05-20 13:52:35Z ru $
@


1.3.36.1.8.1
log
@SVN rev 232438 on 2012-03-03 06:15:13Z by kensmith

Copy stable/8 to releng/8.3 as part of 8.3-RELEASE release cycle.

Approved by:	re (implicit)
@
text
@@


1.3.36.1.8.2
log
@Switch importer
@
text
@d39 1
a39 1
.\" $FreeBSD: releng/8.3/share/doc/usd/21.troff/m5 96992 2002-05-20 13:52:35Z ru $
@


1.3.36.1.6.1
log
@SVN rev 216617 on 2010-12-21 17:09:25Z by kensmith

Copy stable/8 to releng/8.2 in preparation for FreeBSD-8.2 release.

Approved by:	re (implicit)
@
text
@@


1.3.36.1.4.1
log
@SVN rev 209145 on 2010-06-14 02:09:06Z by kensmith

Copy stable/8 to releng/8.1 in preparation for 8.1-RC1.

Approved by:	re (implicit)
@
text
@@


1.3.36.1.2.1
log
@SVN rev 198460 on 2009-10-25 01:10:29Z by kensmith

Copy stable/8 to releng/8.0 as part of 8.0-RELEASE release procedure.

Approved by:	re (implicit)
@
text
@@


1.3.34.1
log
@SVN rev 191087 on 2009-04-15 03:14:26Z by kensmith

Create releng/7.2 from stable/7 in preparation for 7.2-RELEASE.

Approved by:	re (implicit)
@
text
@@


1.3.32.1
log
@SVN rev 185281 on 2008-11-25 02:59:29Z by kensmith

Create releng/7.1 in preparation for moving into RC phase of 7.1 release
cycle.

Approved by:	re (implicit)
@
text
@@


1.3.30.1
log
@SVN rev 183531 on 2008-10-02 02:57:24Z by kensmith

Create releng/6.4 from stable/6 in preparation for 6.4-RC1.

Approved by:	re (implicit)
@
text
@@


1.2
log
@Remove original license disclaimer.
Add Caldera license.

Approved by:    David Taylor <davidt@@caldera.com>
@
text
@d461 2
@


1.1
log
@Initial checkin: 4.4BSD version.  These files need to be updated with
current license information and adapted to the FreeBSD build
environment before they will build.
@
text
@d1 35
a35 3
.\" This module is believed to contain source code proprietary to AT&T.
.\" Use and redistribution is subject to the Berkeley Software License
.\" Agreement and your Software Agreement with AT&T (Western Electric).
@

