This is the file containing the INFO-ized documentation on using
R with its standard macro package.

This file describes how to use R with its standard macro
package, and contains information on essentially all features
available.  The earlier sections of this file deal with general
topics of using R, and explain some of the common things that
most R users need to understand (at least a little) to use R
effectively.  We have tried to write all parts so that the
beginning user can glean enough information to get started, but
also so that the advanced user can get help on all but the most
arcane things.

Whereas the goal of the R Reference Manual (see node
Documentation for pointers to documentation) is to explain
precisely everything in R, the goal of this file is describe
how to use things effectively.  Another difference is that the
reference manual describes "raw" R, that is, R minus the macro
package, but it is the macro package that provides most of the
"friendly" features users exploit.  Here we desire to explain
the use of the macro package as it is, and also how to tailor
it to do slightly different things.  We also give some guidance
and lore on how to debug documents, and hints on writing your
own macros.  However, to do all this, we must explain a lot of
things, many of which need not be understood by novices.

Therefore, the sections are usually written so that they start
with simple cases, with simple examples that can be used almost
like recipes.  Then they progress to explanations of what is
really going on and more advanced examples.  Novices should
start at the beginning -- Generalities, since this gives a
brief orientation, and tells you about a number of simple
mechanical things.  If just starting, you should also go
through the first four or five sections at least.  Do not worry
if there are things you do not understand on first reading;
they should become clear as you start actually preparing
documents.

Comments and suggestions on the form and content of this guide
would be appreciated.  Send them to EBM@XX.

			1. This is the first item in a list.

			2. This is the second item, and is a bit
			longer, so it takes up more than one
			line.

			The list facility is quite flexible and
			powerful.

Here we give you some orientation as to what R does and to get
started using it.  The next node, Setup, gives you tips on
organizing your input file.

R is a text formatting program.  Its place in the process of
preparing documents is illustrated by the following picture:

you -> editor -> input file -> R -> output file -> output program -> document
			       |
			       +--> error messages

The above picture means that the common way of preparing a
document involves these steps, in order:

1. You prepare an INPUT FILE using your favorite editing
program.  A FILE is a repository of data in the computer
system.  The way most of out editors work, you simply type the
text in to the editor, and then when you think it is ready, to
give the editor a special command, telling it to write what you
have typed in, to a file on the computer system.  You can also
edit files you have made before, to correct mistakes, add new
text, etc.  The most commonly used editors are EMACS, RMODE,
and TED.

2. You then run R, telling it to process the input file you
created with the editor.  The term "invoking" means the same as
"running" in this context.  People will say "Run R" or "Invoke
R" just about as readily.  R then produces an OUTPUT FILE, and
possibly some error messages and other information.

3. If there are no errors, then you invoke the appropriate
program to send the output file to the output device.  Here are
the programs you would use for the most common situations:

	Device		on ITS		on TOPS-20 (XX)

	PRESS (Dover)	DOVER, DOVR	DOVERSEND (and DOVER, coming soon)
	XGP		XGP		XGPSEND
	LPT		TPL

If there are error messages, or the document does not have the
desired appearance, you back back to step 1, and create a new
input file that you think will work better.  It may take doing
this half a dozen times to get rid of the "bugs" in a new
version of a document.

R normally prints its error messages on your terminal as it
runs.  However, it is often better to save them in a file, so
that you don't have to write down what is on your screen to
avoid losing the messages.  See the section on invoking R for
information on how to do this.

Some of the other text formatters available are: (Opinions
expressed are mine, but I have found many experienced users to
agree with most of these statements.)

	SCRIBE - has approximately the same capabilities as R,
		and about the same strong and weak points.
		Easier for the novice to use than R, but maybe
		harder for the expert to get what s/he wants.
		Can do single or multiple pass processing.
		Not available on ITS at this time, maybe never.
	TJ6 - a very simple minded, easy to use formatter, with
		superficial similarities to R.  Most people find
		TJ6 too simple: there are too many things it
		cannot do.  Available only on ITS.
	PUB - a powerful but often arcane formatter.  Slower
		than R, but it can do a few more things than R
		can.  Available only on ITS.
	TEX - Good for mathematical things like equations and
		tables, but not as easy to use as some of the
		other formatters.  Not as convenient as other
		formatters on non-mathematical documents.
		Available only on ITS

In sum, R may not be for you.  But you should know that R is
the only text formatter we have that runs under all our
computer systems.

The diagram of the document preparation process that we drew
above is overly simple: sometimes one processes the input text
some before giving it to R, and sometimes one processes the
output file some before printing it out.  An example of the
first situation is this: you can run a spelling checking and
correcting program (e.g., ISPELL) to find spelling errors
before running R.  Some examples of the second situation are:
you may use a program that extracts only the pages that have
changed between versions of a document (e.g., @ or XGPDIFF), or
you may have to run RALP on line printer output (see node
Devices).

The documentation on R itself consists of the R Reference
Manual.  That document is pretty good for the experienced
and/or sophisticated user, but is tough going for the novice
(sort of like reading an encyclopedia!)  The manual exists in
online readable form (suitable to read into a text editor,
etc.) as R;RDOC LPT on ITS, and DOC:R20.MANUAL on XX.  To
acquire a nice looking copy, send MC:R;MANUAL PRESS to the
Dover.  If you don't know how, talk to somebody who does.

There is an R Primer in preparation by another person (Judi
Jones).  That document should complement this one, in that the
Primer is something you can sit down and read all at once.
This guide goes farther, and is therefore longer.  We recommend
that most parts be skimmed on first reading.  Having two
different explanations of the same thing should help; we have
tried hard to make sure that the two documents do not say
contradictory or wrong things.

Documentation on the macro package consists of this file, and
also R;RMACRO INFO (<R>RMACRO.INFO on XX -- from now on, assume
the XX name is the one corresponding to the ITS name unless
told otherwise).  Either file may be printed on your terminal
or a line printer.  (This file is INFO;RMACRO INFO.)  The other
file may be retired if this one works out.

The macro package itself comes in two parts.  By special
dispensation, the larger part, R;R30M RMAC, is pre-loaded into
R when you get it.  The smaller part, R;R30 RMAC, is inserted
by R;R MACROS, and must be read every time.  It activates the
larger package, and helps in option selection.  However, if you
desire to inspect these file, you should look at these
versions: R;R30M RML and R;R30 RML.  (RML = R Macro Language.)
The difference is that the RML files are nicely indented and
have comments, whereas the RMAC files have been compacted by
throwing away the indentation and comments.  If you want to
write things in the "R Macro Language" yourself, you should
realize that R will not accept them as they are, because the //
comment form is not understood by R.  You can use ^K instead of
//, or you can convert your RML file to an RMAC file using the
TECO macro in R;RML >.  For XX users, there is a program in
<R>RML.EXE that will do the job; just type <R>RML file-name,
and it will create a new file, with second name RMAC, with the
compacted version in it.

Documentation on auxiliary macro packages is usually included
as comments in the beginning of the file containing the extra
macros.

There is a mailing list, INFO-R, to which messages concerning
changes to R and the standard macro package are sent.  If you
wish to be added or removed from that list, send mail to the R
maintainer (currently EBM@XX).

The file R;R ARCHIV contains a record of all changes made to R
in recent history (it goes back several years), except the most
recent changes, which are described in R;R RECENT.

R;RMACRO RECENT contains information about recent changes to
the standard macro package.  R;R STATS gives a summary of R
usage from the time R began, by user, in order of amount of
stuff processed.

The primary home of all R files and documentation is XX; ITS
and other versions are updated from there.

Complaints, suggestions, and problems may be referred to the
maintainer (EBM@XX), by sending mail directly, or by using
:BUG R on ITS (which is the same as :MAIL BUG-R@AI).  Please do
what you can on your own first!  See the node on Debugging for
hints.

Read the section pertinent to your system, and then read the
note at the end.

On ITS:
	Full filenames on ITS have the form:
		device:directory;name1 name2
	In the .so command of R, you may
		omit device: if it is DSK:
		omit directory; if it is your directory, or R;
		omit name2 if it is >, R, or RMAC
	In the .fo command of R, you may
		omit device: if it is DSK:
		omit directory; if it is your directory, FONTS;,
			FONTS1;, FONTS2;, XFONT;, or R;
		omit name2 if it is KST
	NOTE: In the command line, filenames may NOT have spaces
	in them.  Thus, ':r foo >' will NOT do what you might
	expect!  However, the second name need not be given if
	it is R, RMAC, or >.  If you must supply a second name,
	there are two ways:
		:r "foo bar"	-- put the file name in double quotes
	The other way involves a different format of filenames,
	and is explained in the reference manual.

On TOPS-20:
	Full filenames on TOPS20 have the form:
		device:<directory>name1.name2.version
	In the .so command of R, you may
		omit device: if it is DSK:
		omit <directory> if it is your directory or PS:<R>
		omit name2 if it is R or RMAC
		omit version it is the most recent one (0)
	In the .fo command of R, you may
		omit device: if it is DSK:
		omit directory; if it is your directory,
			PS:<FONTS>, PS:<FONTS1>, PS:<FONTS2>,
			PS:<XFONT>, or PS:<R>
		omit name2 if it is KST
		omit version if it is the most recent one

NOTE: To make files more easily portable from system to system,
you should try to arrange things so that you can omit the
device, directory and name2 fields in as many cases as
possible.  R was purposely designed to make this easy in most
cases.  For example, unless you made up a font file yourself
and gave it a funny name, you never need to state the device or
directory for a font.  Similarly, it is conventional to set
your input file's name2 to be > on ITS (R on XX), and to use a
name2 of >, R, or RMAC for auxiliary input files.  If you do
so, then you will not have to state the name2 to R.  Since
almost all files will be in your directory or the R directory,
this means that most of the time you need only state the name1
of the desired file.  In the cases where you need name2,
writing the filename as name1.name2 works on all systems.
There is no nice way to include a directory or device that can
be read on all systems with no changes.  Therefore, we suggest
that you omit as many of the filename fields as you can.

R can produce output for several different printing devices.
These devices are distinguished mainly because to get the same
appearance of an input file on different devices requires
different instructions in the output file which is sent to the
device.  Another reason for distinguishing the devices is their
different capabilities.  For example, the XGP, Dover, and
Varian all support multiple fonts with characters of varying
widths.  The Diablo supports a single font, but can do
relatively fine grained positioning on the page, and line
printers have a single, coarsely positioned font.  (Font means
typeface.)

R is designed so that it is comparatively easy to make up a
single file that can be output on several different devices by
just telling R what device you want.  Of course, R can't do
anything about some devices not having the special characters
you may want, but with a little care, on can often get
reasonable drafts from less fancy devices.

When R produces output for a given device, the name2 of the
output file is set to the device name.  For example, if your
input file is called FOO.R, and you produce output for the XGP
device, the output file will be called FOO.XGP.  The only
exceptions to this rule are the Diablo device and 12 pitch line
printer output; see the reference manual for details.

Below is a list of the devices and their interesting
properties.  See also the Setup node and the Invoking R node.

LPT - line printer.  A single font, fixed character width
device.  Generally, files produced for the LPT are also
suitable for inspection with a text editor.  This is often
helpful in debugging.  Although you only get one output font,
you can have R mark things supposed to be in different fonts by
underscoring them, printing the characters several times (to
darken their appearance), or capitalizing them.  See .FO in the
reference manual for details on that.
	NOTE: the macro package assumes that LPT files will be
printed by a program on the operating system, and makes certain
adjustments not described in the reference manual.  If this is
a problem, set the number register LPT_HACK to 0 before loading
the macro package.
	NOTE: if you use superscripts, subscripts, or related
things, R will give you a message "postprocessing needed".  In
such cases you should run RALP (random access line printer).
Just type
	:RALP FOO  where FOO is the name of your input file
(RALP FOO on TOPS-20, etc.).

PRESS - press file.  This is the format accepted by a number of
devices constructed by Xerox Corp., including our Dover (but
NOT the XGP, also made by Xerox).  This supports multiple fonts
and very fine positioning (units of 10 millionths of a meter in
theory, 384 dots to the inch on the Dover).  Press fonts are
those available on a special list (see FONTS;DOVER FONTS).
There may be a complete catalog of these available sometime; a
few copies of a limited catalog might still be available from
Anne Rubin in Room 529.  Unfortunately, the fonts available for
the XGP and the Dover are different, even similar ones have
different names.  The first 1/3 of an inch (at the top of the
page) cannot be used (hardware limitation).

XGP - Xerox Graphics Printer.  Capabilities similar to the
Dover.  Output quality is not as good, and printing is much
slower on the XGP, but many more fonts are available, and it is
easier to make up new ones than for the Dover (it is almost
impossible for the Dover).  Each font comes from a different
file, so the fonts are specified by giving the name of the file
containing the font.  Most of these fonts live in FONTS,
FONTS1, and XFONT, with some "personal" ones in FONTS2 and
elsewhere.  The old catalog is out of print.  A new catalog
will be available after the ongoing font reorganization is
complete.  The XGP device cannot go up the page; all other
devices can, more or less.

VARIAN - Varian printer/plotter.  This has almost exactly the
same properties as the XGP, including the available fonts.  It
is connected to the 4th floor 11/70 UNIX system.  You should
talk to them for more information.

DIABLO - Xerox 1700 terminal (Diablo mechanism) - This is
similar to a line printer in that is has only one, fixed width,
typeface, but it can do fine positioning both horizontally and
vertically.  Output is very sharp with a carbon ribbon.  See
the file R;DIABLO INFO for more information on using the Xerox
1700 on the 5th floor.

In this node, we discuss the command line in general, list the
specific options and flags available, and, at the end, give
some special notes for ITS and TOPS-20 users.

Using the command line.

	When you run R, you do it by typing the name of R
(e.g., "R") followed by the name of your input file.  For
example:

	(ITS)		:r foo
	(TOPS-20)	r20 foo

This handles many common situations, but there are a number of
options you can specify.  Most options are FLAGs.  A flag is
one or two letters, preceded by a dash (-), with the whole
thing separated from anything else on the line by spaces.  For
example:	:r foo -x -s

The flags are discussed in three groups below.  In addition to
the filename and flags, there are two other things that may
appear on the command line.  One is a request to send the error
messages to a file instead of the terminal screen.  To send
error message to the file foo.bar, put >foo.bar at the END of
the command line.  For example:
	:r foo -x -t >foo.err

The other kind of thing that may appear on the command line, is
an initial setting of a number register, like this: reg=value.
Here is an example:
	:r foo -x figure_debug=1

Device options:

	You can override any .dv in your file and get R to
produce output for a particular device by putting the right
flag in the command line.  Here are the flags for each device:
	-p   Press
	-x   XGP
	-l   LPT
	-di  DIABLO
	-v   VARIAN

Miscellaneous options:
	-s   prints extra statistics
	-t   does a TRACE of the execution (see node Debugging)
	-d   debug -- causes some extra output regarding
		figures, footnotes, etc. (see node Debugging)

Pitch and Lines per inch options:

	You can override the default pitch and/or lines per
inch, or any .pi or .lp commands in your file, by putting the
right flag in the command line.  This is useful mainly for the
Diablo device, but pitch applies to to the LPT device as well.
	-10p  use 10 pitch (10 characters to the inch; Pica)
	-12p  use 12 pitch (12 characters to the inch; Elite)
	-6l   use 6 lines per inch as single spacing
	-8l   use 8 lines per inch as single spacing

Special things to know on ITS.

	Don't forget that filenames in the command line cannot
contain spaces!  This includes both the input filename and the
name of the file to receive error messages, if any.  If this is
a problem, see node Filenames for a way around it.

Special things to know on TOPS-20.

	Because "R" is a command on TOPS-20 (meaning "run the
program whose name follows"), R is called R20 on TOPS-20.  So,
you might invoke R this way:  R20 foo -p >foo.errors

If you are new to R, I suggest you put the lines shown below at
the beginning of your file, until you understand better what it
all means.  (It is explained below, but it may take using R for
a while until you will understand it.)

.dv press
.if press
.  fo 0 TimesRoman12
.  fo 1 TimesRoman12b
.  fo 2 TimesRoman12i
.  fo 3 TimesRoman18
.else
.  fo 0 times.12rom
.  fo 1 times.12bold
.  fo 2 times.12ital
.  fo 3 times.18rom
.  end if
.tr @
.so r.macros
<start your document here>

The .DV line means that your default device will be the Dover
(Press file format).  The ".if press" says if the device really
is PRESS (you can override it in the command line; see node
Invoking R) then continue with the immediately following .FO's;
otherwise, continue from the .ELSE.  This used to get one set
of font definitions when you use the Dover, and another set
when using the XGP (or any other device).  This is really the
only way to do it.

The .FO lines define four fonts:
	font 0 - a normal text font, I have given you Times
		Roman, 12 point (1 point = 1/72 inch; points are
		a standard unit of measurement in typesetting).
	font 1 - a bold font, set to match the normal font
	font 2 - an italic font, also matching the normal font
	font 3 - a big font, for chapter headings, etc.

You may use any fonts you like, of course, and you may define
more, to get special symbols, greek characters, etc.  But the
standard macro package always assumes that font 0 is a normal
font, font 1 is a bold font, font 2 is an italic font, and font
3 is a big font.  For the diablo or lpt, it does not matter at
all what fonts you put down, but you must put something down
for these 4 fonts.  For more about fonts, see node Fonts.

The .TR command sets things up so that the character '@' will
print as a space instead of an @.  Now that may not sound
useful, but it is, because the space character, ' ', does not
exactly print as a space, but usually means "put some white
space here, or, if you are close to the end of a line, start a
new line".  The node Input starts to explain the difference,
and node Justification explains this particular case in detail.

The .SO command activates the standard macro package.  It turns
out that most of the macro package is loaded into the R that
you run, since it takes a while to read it into R, and people
use R all the time.  BUT! you must still turn it on by reading
a smaller file that starts things off.  You must have no text
or blank lines before this .SO.

The above setup gives you the standard macro package with its
default options.  If you decide there are things you don't like
about some feature or other, consult the appropriate section,
to understand what things can be adjusted, and how.  Then, you
may wish to insert some lines to override the default options.
These lines should go just before the .SO above.  You will most
likely have to read up on string and number registers (next
node) and possibly input processing (Input) to understand how
to get what you want.

This node describes things you should know about how R
processes your input file.

At all times, R reads a character at a time from some place,
until it reaches the end of your file.  The various places R
can be reading from include:

	Files
	String and number registers
	Macro bodies
	Macro arguments
	and a few other internal sorts of things

For example, when R reads the setup described in the previous
node, it is reading from your input file, from the beginning to
the end.  However, when it sees the .SO, it starts reading from
the named file (R.MACROS).  Then, when it reaches the end of
that file, it returns to where it left off in your file.  This
process can be carried to MANY levels (about 20-30 in the
current R).  The reference manual refers to this changing of
where R reads from as "input stream switching".

The next thing to understand is that except for stream
switching commands, which effectively disappear, the characters
read are grouped into lines, which are processed one at a time.
Normally each line that you type becomes a single input line;
if you find yourself typing a lot of long lines, read up on the
line continuation feature in node Continuation lines.

There are two different kinds of input lines:

	Requests and macro invocations, and
	Text

Requests and macro invocations are readily recognizable: they
are the lines that start with "." or "'".  For example, the
line
	.dv press
is a request line.  The request is the thing following the "."
(dv in this case), and the rest of the line forms the ARGUMENTS
to the request.  Of course, the meaning of these arguments
depends on the request.

Macro invocations LOOK exactly like request lines.  The only
distinction is that requests are built-in, and macros are
written in terms of requests.  This distinction is not very
important, but it may help you to know the two terms.  Here is
an example macro invocation:

	.chapter "Title of Chapter One."

Text lines are line that do not start with "." or "'", and
most, but not all, characters on a text line will appear in the
output.  Let us examine the situation here in more detail,
since you may need to know most of this to construct good input
files.

Assume R encounters an ordinary character, say "D".  What R
will do is put something in the output file that tells the
output device to print whatever corresponds to a "D" in the
current font.  We phrased the previous sentence in a somewhat
awkward way to make a point: just because you have a "D" in
your input file does not mean that the appearance of the
character will be that of a "D".  In fact, R knows nothing
about the actual appearance of characters at all!  R only knows
how big they are, so it can figure out where to put them on the
page.

Some characters that appear in the running text are used to
tell R to change what it is doing in some way.  These
characters are the CONTROL CHARACTERS.  They are called control
characters both because they control R's behavior and because
most of the particular characters in question are normally
typed as ASCII control characters.  An example is ^F
(pronounced "control F"), which is used to change the current
font.  NOTE: we write control characters as two characters in
this document (an "^" followed by a letter) to avoid certain
mechanical difficulties, but "^" followed by "F" is NOT the
same as control-F.

Control characters bring us straight into a thorny problem,
however.  Fonts can have characters associated with ANY of the
ASCII characters, including the ASCII control characters -- how
can we possibly get the symbol corresponding to a ^F if ^F
means change fonts?  What we do is this.  Inside R there are
two kinds of control characters, which we will call the R
CONTROL CHARACTERS and the TEXT CONTROL CHARACTERS.  An R
control character performs a special function, such as ^F
changing the font.  A text control character causes a character
to be added to the text output.

When a control character is written by itself, it is taken as
an R control character, i.e., it performs its special function.
However, the R control character ^Q has the particular function
of taking the next character, no matter what that character is,
and turning it into a text control character.  In sum, ^F means
change fonts, and ^Q^F means output the character corresponding
to ^F in the current font.  ^Q^Q, therefore, is the way to get
a text control-Q, etc.

NOTE: most editors require a special command for you to get a
control character into your file, and that command is usually
^Q.  For example, to get a ^F into your buffer, you must type
^Q^F in most of our editors.  Further, to get ^Q^F into your
buffer, you must type ^Q^Q^Q^F, etc.  To get a ^_ or ^Z into
your buffer on ITS requires more devious means -- ask somebody.
(The same holds for getting ^C into your buffer on TOPS-20.)
Fortunately, these characters are almost never used.

NOTE: for some help on techniques to ease problems with
characters that are hard to type, or hard to get R to accept
(e.g., ^J, ^M, and ^L) see the discussion of escape characters
in node Backslash.

For completeness here is a list of the R control characters:

	^A, ^B, ^C, ..., ^Z	the ASCII control characters
	\
	space    that is, " "
	. and '    when appearing at the beginning of a line
	    (So, to get a . at a beginning of a line, write
	     "^Q.".)

Most of these are explained fairly well in the R manual.  You
should definitely read about the control characters ^A through
^Z.  You already know that control-. and control-' are used in
request and macro invocation lines.  Control-\ is explained in
node Backslash, and Control-space is explained in node
Justification.

Additional Features:
	Normally control characters in the input turn into the
corresponding R control characters.  You may use the .CC and
.NC requests to change the exact mapping, however.

	.cc c p - causes the input character "p" to become an R
		control "c"

	.nc p - causes the input character "p" to become a text "p"

You might also be interested in reading the description of
escape characters in node Backslash.

R has NUMBER REGISTERS and STRING REGISTERS, which are very
useful.  It is hard to give an easy to understand explanation
of exactly how they work, but they turn out to be easy to use
in the common situations.  Let us consider an example.

Say that you find you are typing ^F5^Q^N^F... quite a lot,
because it is a special character used many times in your
document.  Let us say that it is a summation sign (capital
sigma).  You can define a string register to give you a handy
abbreviation for that:
	.sr sum ^F5^Q^N^F*
Then, wherever you want the summation sign to appear, just
write "^Ssum".  The .SR command ("string register") has two
ARGUMENTS, a name for the string register ("sum" in this case),
and the stuff to put in it.  The name begins after the space
after the .SR, and continues to the next space.  Register names
(this holds for number registers, too) can have only these
characters in them: A through Z, 0 through 9, and _.  Case
(upper or lower) is ignored.

The stuff that goes into a string register starts with the
first non-space, non-tab character and continues to the end of
the line.  If you need the first character of the stuff in a
string register to be a space or a tab, precede it by a
backslash.  For example:  .sr foo \ abc

The above puts space, a, b, c into the string register FOO.  If
you want to set a string register so that it has nothing in it,
then just put nothing after its name, e.g.:  .sr foo

Whereas as string registers hold strings (a technical name for
a bunch of characters), number registers hold numbers.  Number
registers hold whole numbers (integers) only, and positive and
negative numbers are allowed.  The biggest number you can put
into a number register depends upon what computer system you
are using, but is always at least 15000.  As we saw before, the
contents of a string register can be made to appear by typing
^S followed by the string register name.  To get the value of a
number register to appear, we use ^N followed by the number
registers name.  Similarly, we use .nr to set a number
register.  Here is a simple example:
	.nr foo 105
	The serial number of the stolen item was ^Nfoo.

What will appear in the output is:
	The serial number of the stolen item was 105.

The particular example above could have been done with a string
register.  The important thing about number registers is that
you can use them to make calculations, to count things, etc.  A
simple example is that the macro package has a number register
named chapter that always holds the number of the current
chapter.  This is nice because it lets us write down once the
format for the header line of a new chapter:
	^Nchapter.  ^Schapter_title
Instead of writing that down in each place, we do this:
	.sr chapter_form \^Nchapter.  \^Schapter_title
The exact meaning of the backslashes is made clear in node
Backslash, but suffice it to say that if you leave them out,
you will certainly not get what you want.  Anyway, when we want
the line to come out, we can just do:
	^Schapter_form
and the chapter number and title will come out.

Number registers can also be inserted as Roman numerals (upper
or lower case), or alphabetics (1 => A, 2 => B, 3 => C, etc.)
by putting a special character just after the ^N.  See the
reference manual's description of ^N for a list of these.

Similarly, string registers may be inserted in upper case,
lower case, or capitalized (first letter upper case, rest
lower) by putting a special character just after the ^S.
Again, we refer you to the reference manual for details.

IMPORTANT:  Remember how we describes R as reading a character
at a time in node Input?  Well, when a ^N or ^S is encountered,
R reads along until it finds a character that cannot be part of
a register name.  All the characters is has read between the ^N
or ^S and that point are grouped together to make a register
name, and then the value of the register is looked up.  There
are some problems you might encounter because of the way this
works.  For example:
	.nr foo 100
	10 times 10 times 10 equals ^Nfoo0.
In this example, R will try to look up a number register called
foo0, and will NOT try to find foo.  The way out of this
problem is to write the second line like this:
	10 times 10 times 10 equals ^Nfoo!0.
We say that the ! TERMINATES (ends) the register name.  By
special dispensation, the ! is thrown away.  Therefore,
	.sr foo BAR
	And I say FOO ^Sfoo!
will print as:
	And I say FOO BAR
Whereas
	And I say FOO ^Sfoo!!
will print as
	And I say FOO BAR!

One final situation should be mentioned, which is less common,
but you might need to know about it.  It is possible to read
part of the name of a register from another register:
	.sr b bar
	.nr foobar 1000
	10*10*10 = ^Nfoo^Sb.
will print as:
	10*10*10 = 1000.
You may need to use ! in such situations.  Here is a hairy
example for you to think about:
	.sr b bar
	.sr f foo
	.sr foobar form
	R is a text ^S^Sf!^Sb!!atter.

An expression is a way of writing down a little computation for
R to perform.  Expressions are used in many requests.  Some of
these requests, for example, .NR, are looking for just a
number, and others are looking for a description of a
horizontal or vertical distance.  (Horizontal and vertical
distances are distinguished mainly because they involve
different actions on the part of output devices.)

The simplest thing you can put in an expression is a number,
such as 1, or 2.5, or .001, etc.  If the situation calls for a
whole number, R will round the expression to the nearest whole
number for you; halves round down.

The next simplest thing you can put in an expression is the
name of a number register.  It will be treated as if you put a
^N in front of it.  Note that there are occasions where you
must put an ! after the number register name to show R where it
ends (see node Registers for more information on this use of
!).

Beyond simple numbers and number registers, you can compute and
combine expressions into larger expressions using the various
OPERATORS.  The reference manual has complete details, but here
are some of the highlights.

	+, -, *, / stand for addition, subtraction,
		multiplication, and division
	+, - may also be used in the sense of +1, -1, -n, etc.
	parentheses, ( and ). may be used to group parts of an
		expression, e.g., (a+b)/(c+d)

No spaces should appear in an expression.

Besides computing numbers, expressions can be used in the sense
of logical or truth values; 0 means false, and not 0 means
true.  For example,  .if press  says go on if "press" is true,
namely, if the number register press is not 0, which happens
only when the output device is Press.  Here are some of the
operators used this way:
	==, ~=  return 1 (true) if the left-hand and
		right-hand expressions are equal (==) or not
		equal (~=), and return 0 otherwise.
	<, <=, >=, >  return 1 if the left-hand expression is
		less than, less than or equal, greater than or
		equal, or greater than the right-hand
		expression.
	&, |  returns 1 only when both (&) or at least one (|)
		of the left- and right-hand expressions is true
	~   returns the opposite truth value, i.e., it means
		"not", as in ~(a&b)

Here are some examples taken from the macro package:

	.nr chapter chapter+1
	.if toc_level>0
	.if ~ignore_level        (a trick; the same as .if ignore_level==0)
	.if table_of_figures&~ignore_level
	.if (last_fig_pos~=vpos)|(last_fig_page~=page)
	.nv one_line ls*fheight/100

Horizontal and Vertical Expressions:

	These consist of a regular expression, possibly
followed by a letter to indicate some measurement unit, e.g., c
indicates centimeters.  See nodes Page Layout and Line Layout
for more details on these units.  Here are some examples to
show what you can do:
	.sp (fheight+100)m
	.hp ll-rindent!m
	^V(+delta1!m)
	.hs -(wid1+wid2)/2m

This node may (and perhaps should) be omitted on first reading.

The \ characters turns into R control-\ when read, unless
quoted with ^Q (see node Input for that discussion).  The
purpose of the R control-\ character has not been made clear,
however.  It turns out that there are four distinct uses of \
in R:
	as a text character (when quoted with ^Q)
	to indicate ESCAPE CHARACTERS
	to PROTECT R control characters
	to indicate continuation lines

Escape characters provide a convenient way of writing down
characters that are otherwise hard to type.  There are 26
escape characters, called escape-A, escape-B, ..., escape-Z.
They are written \a, \b, ..., \z (you can use upper case
letters if you like, but they mean the same as the lower case
letter).  The .EC command is used to say what character you
want a particular escape character to really be.  For example:

	.ec c ^C

will cause \c to mean ^C (that is, R control-C) whenever it is
seen in the input.  Most escape characters mean nothing when R
starts, and it will print an error message if you use them.
However, the following are pre-defined, because it is
impossible to get them otherwise:

	\n as text ^J	(n for newline)
	\r as text ^M	(r for return (carriage return))
	\p as text ^L	(p for page (form feed))

It is not recommended that you try to get these characters any
other way -- it may work on some systems and not others,
because different combinations of these are used to indicate
line boundaries.

Here we describe the primary use of \ in macros and string
registers, which is to "protect" control characters, i.e.,
prevent the control character's action from being performed
until the right time.  This is best explained by means of some
examples that illustrate the problem that \ is intended to
solve.

We take our first example straight from the standard macro
package.  There is a string register named center_heading that
is inserted (using ^S) in the middle of the top of the page, to
print a heading.  Normally it prints:
			- page -
where page is the current page number.  Now, consider how we
might DEFINE center_heading originally.  Here is a try:
	.sr center_heading - ^Npage -
This is a good try, and shows some understanding of how string
and number registers work.  However, it will result in this
being printed at the top of every page:
			- 1 -
The problem is that the value of the number register "page" is
sampled at the time the string register "center_heading" is
defined, so center_heading's contents turn out to be "- 1 -"
instead of "- ^Npage -".  What we need is a way of saying "I
want to put a ^N into the string register, not look up the
number register right now".  That is exactly the function of \.
Here is the correct way to set center_heading to get the
desired effect:
	.sr center_heading - \^Npage -

Now you may be able to understand an earlier word of wisdom
that we asked you to take on faith, namely:
	.sr foo \ abc
puts a space, a, b, and c into string register foo.  What you
are getting is a protected control space.  A protected control
space is clearly not the same as a control space, and it is
control spaces that are skipped between the arguments to a .SR.
So now you should understand both why the \ is required, and
why it works.

Backslashes can be used to protect ANY R control character from
being INTERPRETED (interpreted means being gobbled and causing
a special action), however it is needed only in the cases where
the control character would be interpreted anyway.  The
reference manual explains the exact situation in more detail,
but the only control characters that commonly require
protection are ^N, ^S, and ^A.  Sometimes you might have to
protect a control-., control-', control-space, control-I (tab),
control-J (newline), ^Q, or ^K, but those situations tend to be
more rare.

Multiple backslashes.

	Occasionally it is required to put more than one \ in
front of a control character.  Here is an example:
	.sr heading ^Sleft_heading^C^Scenter_heading^R^Sright_heading
This is supposed to set up a single string register so that
when inserted with ^S it will print the left heading on the
left, the center heading centered (the ^C centers stuff), and
the right heading flush against the right edge (^R does that).
But those headings are each defined separately in different
string registers.  Once again we run into the problem that if
we do:
	.sr center_heading - \^Npage -
we will not get nice headers.  The reason is that although
center_heading has "- ^Npage -" in it, when we put
center_heading into heading, the characters are read again, and
the ^N will be interpreted, resulting in heading containing
this:	...^C- 1 -^R...   which is not what we wanted.  One
solution is to define center_heading this way:
	.sr center_heading - \\^Npage -

We say that the ^N is protected TWICE in this case.  R is
willing to let you protect a control character many times (at
least 9, anyway).  In general, something may be read many times
if it is moved from register to register, and it is necessary
to know how many times it is moved in order to get the number
of \'s right.

Because this is inconvenient to do, and makes changes hard,
another feature was introduced to make doing this kind of thing
easier.  If the ^S used to insert a string register is followed
immediately by a ":", then every control character in the
string has an extra \ put in front of it before it is inserted
in the input stream.  This prevents interpretation of any
control characters in the string, and means that the initial
setup requires just one backslash.  Here is the example above
reworked with this ":" feature:
	.sr center_heading - \^Npage -
	.sr heading ^S:left_heading^C^S:center_heading^R^S:right_heading

You should know that there are cases where multiple backslashes
are still needed; however, these generally occur in more
sophisticated things, such as macros that define macros, etc.

If you put "\!" at the end of a line, then the \, !, and the
newline all disappear from R's input, as if they were never
there.  This is convenient when you have long request lines, or
long lines in nofill mode, etc., where it is important that R
THINK that the input is all on one line.  However, when R tells
you a line number, as in an error message, the number is the
real line number in the file.  This makes it easy to find the
relevant place in your file.  \! can be used to throw away ANY
immediately following character, but I have never thought of
anything that is useful for except continuation lines.

There are several sub-topics here, indicated in the menu below:

In NOFILL mode, each output line corresponds to exactly one
input line (except for continuation lines; see node
Continuation Lines).  That is, lines are not FILLED out with
words from succeeding lines to try to make them reach to the
right margin.  Nofill mode is appropriate for tables, program
code, diagrams, etc.  It is often used for title page
information as well.

In FILL mode, words from more than one input line are
accumulated so as to fill out the space from the left margin to
the right margin, as closely as possible without overflowing.
Fill mode is used for normal text.  The newlines at the end of
each input line are turned into justifiable spaces (R
control-spaces, that is).  If you have a period, question mark,
or exclamation point at the end of an input line, an extra
space is inserted, because it is accepted style to separate
sentences by two spaces instead of one.  You should not leave
spaces at the end of input lines unless you really want them in
the output, because they will not be thrown away unless the
line just happens to break there.

If an input line starts with a space, tab, or ^P in fill mode,
then any partial line is output before that input line is
processed.  The same holds for a blank line.  So, for items
indented by hand with spaces, tabs, etc., you do not have to go
to nofill mode or put in .BR's to suppress filling from line to
line.  To get rid of the line break caused by putting a space or
tab at the beginning of a line, you may do one of three things:

	Rearrange the input so that none of the affected lines
	starts with a space, tab, etc.

	Use continuation lines to make the lines look like a
	single input line to R (see node Continuation Lines).

	Use ^G to glue the two lines together.  The ^G may be
	placed at the end of the line preceding the one that
	starts with spaces, or at the very beginning of the line
	starting with spaces (before the spaces).

Details of what happens when a line is broken are presented in
the next node, Breaking.

To get into fill (nofill) mode, the .FI (.NF) request is used.
These requests permit you to set the adjustment mode at the
same time (see node Adjusting).  Another way to control filling
is the FILL number register.  In many cases the number register
is the appropriate thing to use when writing a macro (see
Writing Macros).

Breaks happen in two ways:

	1. when a line gets too much text on it in fill mode,
	and must be broken to start a new line; and

	2. when any partial line is requested to be output, so
	that the next line will start fresh.

The second kind of break happens as a "side-effect" of a number
of requests.  Such requests are said to "break".  For example,
the .SP request, which is used to generate white space, is a
breaking request.  The idea here, as with most breaking
requests, is that you probably want any partial line output
BEFORE the space rather than AFTER it.  All requests that
break, cause the break before they do anything else.  To
suppress the break, precede the request with ' instead of ".".
For example, 'SP will not break, where .SP will.  It is
considered good style to use "." everywhere, except those
places where you really need to suppress a break.

The second kind of break also happens when a blank line, or a
line starting with a space, tab, or ^P is encountered.  Again,
it was done this way because it is usually what you want.  Node
Filling mentions ways of suppressing this.

The first kind of break, the kind caused by overflowing a line
in fill mode, is different from the second kind of break in two
main ways.  First, it is determined implicitly by R, as it
computes how big each letter, etc., is.  Second, after deciding
where to break the line, the text on the line to be output is
justified according to the current adjustment mode (see the
next node, Adjusting).

About spaces:
	R will not break a line in the middle of a text word,
but will break it almost anywhere else.  In particular, R will
break at a control-space (which is what the space character
normally turns into -- see node Input).  One way to prevent a
break at a bad place is to use a text space instead of a
control space.  This can be done by writing "^Q ", but most
people use .TR to TRANSLATE some other character to a text
space when output.  Node Setup suggests that you include the
line ".tr @" in your setup, which will cause @ to be translated
into a text space on output.  That way you can write @ wherever
you want a space that will not be broken.  For example, "foo
bar" may be broken in the middle, but "foo@bar" will not.
However, you should know that it is control spaces that are
widened during adjustment (see node Adjusting), and text spaces
will not be widened.  If you need more sophisticated behavior,
see nodes "Math", and "Writing Macros", for techniques that may
be used to build up formulae or expressions that you do not
want broken in the middle.

Once R has determined what items will go on a particular output
line, that line may be JUSTIFIED before being output.  There
are several different ways this can be done, and they are
controlled by the current ADJUSTMENT MODE.  Let us first
discuss the effects of the different adjustment modes, and when
adjustment will and will not be done, and then describe how to
set the adjustment mode.

R has four distinct adjustment modes:

	LEFT adjusted - The line is output against the left
		margin, and spaces are not widened.  This leads
		to a ragged right edge.
	RIGHT adjusted - The line is output against the right
		margin, and spaces are not widened.  This leads
		to a ragged left edge.
	CENTERED - The line is output centered between the
		margins; both edges will be ragged.
	BOTH - Spaces in the line are widened so that the edges
		of the line come just to the margins.  This is
		what most people refer to as justification.
		NOTE: only control-spaces are widened; text
		spaces are considered to be part of words are
		not disturbed.

The adjustment modes are entirely independent of fill vs.
nofill mode: all eight combinations of fill and adjust modes
are legal, though some are not very useful.  Here are the most
useful ones:

	fill both - used for most text
	nofill left - the usual usage of nofill mode, for
		diagrams, programs, equations, etc.
	nofill center - often used to center one or a few lines
		for a header, title page, etc.

Fill left is sometimes useful for things that look better with
a ragged right edge than with big spaces between the words.
Bibliographies have a tendency to look better in fill left than
in fill both.

The other four combinations, nofill left, nofill both, fill
center, and fill right, just do not seem to be very useful.

R performs adjustment of every output line except those output
in fill both mode by an explicit break.  (An explicit break is
the type of break labelled by a 2 in node Breaking.)
Adjustment is suppressed in this case so that the last lines of
paragraphs will not be stretched out across the whole line.

If you use center or right adjustment in combination with tabs,
^P, or other absolute positioning requests, the result you get
is hard to describe, and probably not what you want.  So, you
should simply avoid doing that.

The ^C and ^R characters provide a more powerful way to center
and right-flush items, even within columns in a line.  See node
Line Layout for more details.

Setting the Adjustment mode.

	R actually remembers the last adjustment mode used with
fill mode, and the last one used with nofill mode, separately.
If you use .FI or .NF with no argument, or set the FILL number
register, the adjustment mode changes automatically to the last
adjustment mode you used with whatever fill moe you are going
to.  On the other hand, you may give an argument to .FI (.NF)
to have to the fill adjust mode (nofill adjust mode) set
explicitly.  That argument consists of a single letter, one of
L, R, C, and B.  For example:
	.nf c
	.fi B
	.nf L
	.fi l
and so on.  The best style is probably to set the adjust mode
every time, so you don't have to remember what is was before,
but it is a matter of personal taste.
	The fill adjustment mode starts as "both", and the
nofill adjustment mode starts as "left", on the grounds that
these are the most common settings.

In addition to the .FI and .NF requests, the adjust mode may be
examined and changed via three number registers: ADJUST,
ADJUST_FILL, and ADJUST_NOFILL.  See the reference and node
Writing Macros for more details.

There are a number of different aspects of this subject:

R permits you to use many different typefaces, called fonts, in
a single document.  Typically one chooses a font for normal
text, and italic and boldface fonts that go well with it.
Also, it is common (and the macro package assumes it) to define
a larger font for section headers, titles, etc.  Beyond that,
it is usually a question of fonts with special characters, such
as Greek letters and mathematical symbols, smaller or larger
fonts for special use (such as a small font for footnotes), and
fixed width fonts for diagrams and programs.

R permits up to sixteen fonts to be defined.  Each is defined
using the .FO command.  You might think that we would number
them 1 through 16, but we wanted to be able to designate a font
with a single letter.  So, we "number" them 0 through 9 and A
through F.  You cannot change fonts in the middle of a
document; you are limited to 16 fonts overall.

The .FO line has these parts:

	.FO <font-number> <font-name> <special stuff>

The <font-number> part consists of a FONT DESIGNATOR, namely,
one of 0 through 9 or A through F.  The <font-name> says what
font to associate with that font number.  The treatment of this
field depends on the output device:

	XGP - you should supply the name of a KST file
		describing the font
	VARIAN - you should supply the name of a VFT file
	PRESS - you should supply the name of a Dover font
	LPT, DIABLO - the field is ignored, and may be blank

For more information on the fonts available and how to specify
them, read the following nodes, or consult the reference
manual:  Filenames, Output Devices, Setup

The <special stuff> part of the .FO line is usually omitted.
However, you can do some useful things with it.  One is to
separately control what file the XGP will use for a font versus
what file R uses to see how big it is.  See the reference
manual for details.  The other thing you can do is to have R
highlight text that is supposed to appear in a different font
when you are producing output for a single font device (LPT or
DIABLO).  For each font, R is willing to do one of four things:

	Nothing - Output the text with no modification.
	Overprint - Print the text several times, to make it
		look bold.  The number register NOVER controls
		how many times each letter will be typed; it
		starts set to 2 (print twice).
	Underscore - Underscore all characters output in the
		given font.
	Capitalize - Capitalize all lowercase letter in the
		given font.

By default, R does font 0 normally (no special highlighting),
and all other fonts are underscored.  You can change this, for
each font individually, by putting a letter in parentheses as
the <special stuff> for a given font.  The letters are:

	n = nothing, o = overprint, c = capitalize, u = underscore

Examples:

	.fo 0 25fg (u)
	.fo 1 25fgb (O)
	.fo 2 25fgi (n)
	.fo 3 37vrb (C)

The most common case of changing fonts is to one or a few words
in another font.  For example, a single word or expression in
italics or boldface, or a special character, such as a Greek
letter or mathematical symbol.  R provides a very easy way to
do that.  You just put ^Fx where you want to change to the
different font, where "x" is the font designator character for
the font you want.  If that sounds confusing, and example
should make it clear.  Say that your Greek letter font is font
6.  To get a sigma, just put ^F6s...  (the ... will be filled
in in a moment).  Similarly, to switch to font A, just write
^FA, etc.

In most cases it is possible to do all font switching
explicitly like this, so the ... above might be filled in with
^F0 to switch back to the normal font:  ^F6s^F0.  However,
there is a better way --  the special expression ^F* means go
back to whatever font you had before the last ^F setting.
Thus, ^F6s^F* means "go to font 6; output an s (sigma); go back
to the font you had before".  R remembers a whole bunch (10) of
these previous fonts, so you can do things like:
	^F2Here is some bold text with one ^F1italic^F* word.^F*
It is considered good style to use the ^F* feature wherever you
can, because it leads to fewer errors.  Note also that R will
produce a warning message if enough ^F*'s are done so that it
would have to back up more than 10 fonts' worth.  That situation
is called "font ring-buffer underflow".

Hint:  When you have a special symbol that is in a different
font, and you use it in many places, you may find it helps to
define a string register abbreviation.  For example:
	.sr sig ^F6s^F*
Here is where ^F* is a MUST, so that you will not switch back
to the wrong font.  Using a string register this way has two
strong advantages.  First, when you see a use in the text, it
is easier to tell what you are dealing with:  ^Ssig conveys
more information that ^F6s^F*, and results in a little less
clutter on your screen.  The other advantage is that if you
change the number of the font, or decide to switch to another
character, you need only change the string register definition
line, instead of every use of a sigma in your file.  So, give
string registers a try!

It you have a large amount of stuff to do in another font, you
can use the .FS request.  For example:
	.fs 2
	... several lines in italics ...
	.fs
.FS takes a font designator character as its argument, so to
switch to font C, you can write:  .fs c (or .fs C).  A .fs with
no letter after it, such as the second one in the example,
works like ^F* -- it means to go back to the previous font.

The standard macro package provides several features to aid you
in font switching; see the next node, Selecting Fonts, for more
details.

There is a fine point of difference between ^F and .FS, that
usually does not make any difference.  However, we mention it
here so you will know about it.  Besides the idea of the
CURRENT FONT, which is the font R uses at any given time for
outputting characters, there is also something called the
PRINCIPAL FONT.  The height of the principal font governs line
separation calculations, along with a number of other factors.
(The details are in node Line Spacing.)  The principal font
also determines the with of a control-space character.  The
point here is that ^F changes only the current font, but .FS
changes both the current font and the principal font.

The number registers FONT and PFONT control the current and
principal font, respectively.  They provide an alternate
mechanism for font switching that is often the most appropriate
one for use in macros.

In cases where you desire to change both the current and
principal fonts to be a particular font, and you do not wish to
use .FS because it uses the font stack, you may use the SET_FONT
macro.  It takes one argument, a numerical expression (number
register names allowed), and sets FONT and PFONT to that number.
Here are some examples:
	.set_font italic_font
	.set_font 3
	.set_font 13

The macro package provides a number of features related to fonts
that should be of assistance to you in document preparation.
First, it provides two ways of switching to fonts that do not
require you to remember which number corresponds to which font.

Method 1:  There are several string registers defined that
contain a ^F and a font designator, to switch to a particular
font.  These string registers are:
	NF - switch to the normal font
	BF - switch to the bold font
	IF - switch to the italic font
These start with the right values in them for the macro
package's normal assignment of fonts:
	normal = 0; bold = 1; italic = 2; big = 3.
Naturally you can change the contents of the string registers
as you please.  Perhaps even more useful, you can convince the
macro package to use different names for the string registers
in question, if the above names are inappropriate.  These
string registers contain the NAMES to use for the string
registers mentioned above:
	nf_reg -- name of string register for the normal font;
		starts as NF
	bf_reg -- same for bold font; starts as BF
	if_reg -- same for italic font; starts as IF
However, any changes to these last three must be done BEFORE
you insert the standard macro package (i.e., before you do the
.SO of the file R.MACROS), and can never be changed later.  This
feature is introduced so that you can use the names NF, BF, or
IF for something else without screwing up the macro package or
yourself.

Method 2:  The macro package provides several macros for
outputting text in a selected font:
	NORM - outputs its arguments in the normal font
	BOLD - outputs its arguments in the bold font
	ITAL - outputs its arguments in the italic font
	BIG - outputs its arguments in the big font
These macros are intended to be invoked inline with ^X (see
node Macro Invocation for further discussion).  Here is an
example use:  ^Xbold(Most of this is bold, but this
^Xital(word) is italic.) You may define more such macros in a
very simple way:
	.def_font_macro foo num
will define a macro with name "foo" that outputs its arguments
in whatever font the number register "num" contains.  Here is
an example:
	.fo 7 hippo
	.nr greek_font 7
	.def_font_macro greek greek_font
and then later:  ^Xgreek(a b g d)  will print alpha, beta,
gamma, delta.

For flexibility, the macro package permits you to control what
font it considers to be the normal font, italic font, bold font,
and big font in the above two methods.  As we have said in
several places, these start as follows:
	NORMAL_FONT - 0
	BOLD_FONT - 1
	ITALIC_FONT - 2
	BIG_FONT - 3
However, by setting the number registers mentioned above, you
will change what the macro package will use.  For example, if
you type ".nr bold_font 6"  then ^Sbf and ^Xbold will use font
6 instead of font 1.  You can change the bold_font number
register, or any of the others, as often as you wish.

In fact, the macro package will automatically change the
definitions of NORMAL_FONT, etc., in certain special cases.
One of those cases is footnotes.  Within a footnote,
normal_font, italic_font, and bold_font are temporarily set to
footnote_font, footnote_italic_font and footnote_bold_font.
This is because many people like to have footnotes printed in a
smaller font.  Here is how you might do that:
	First, put these lines in your setup, i.e., before the
line with ".so r.macros":
	.fo 4 timesroman8
	.fo 5 timesroman8b
	.fo 6 timesroman8i
	.nr footnote_font 4
	.nr footnote_bold_font 5
	.nr footnote_ital_font 6
Of course you can use any fonts you like, and they don't have
to be 4, 5, and 6, or in order, or anything.  The important
thing is that the number for footnote_font be the number of the
font you want for normal text in footnotes, etc.  One thing you
should realize is that if your font is one of A through F, you
must use the letter in the .FO, but the corresponding number
(10 through 15) in the .NR.  For example:
	.fo A timesroman8
	.nr footnote_font 10

If you are using a setup as described in node Setup, with one
set of fonts for the Dover, and another set for the XGP and
otehr devices, you will have to do 2 .FO's, one for each case.
The .NR need only be done once, just before the .SO, provided
you used the same font numbers for the different devices, which
you probably should do, or you will just confuse yourself.

If you ever need to convert a font NUMBER to a font DESIGNATOR,
there are some pre-defined string registers that do it.  The
string register _font_n (where n ranges from 0 to 15) contains
the font designator for the font with number n.  For example:
	.fs ^S_font_^Nital_font

Here is a list of the things for which you can separately
control what font will be used.  The names are the names of
number registers that you can set to select the font you want
for the given thing.  They all have "reasonable" defaults.
Below, toc = table of contents.

	headings: heading_font
	footings: footing_font
	footnotes: fnfont for the superscript number,
		footnote_font, footnote_bold_font, and
		footnote_ital_font for the body
	figures and tables:
		figure_font and table_font for the bodies;
		figure_title_font and table_title_font for the
			title lines;
		figtab_toc_font for the toc entries.
	chapters: chapter_font for the header line;
		chapter_toc_font for the toc line.
	sections: section_font for the header line;
		section_toc_font for the toc line.
	appendices use the chapter fonts.
	subsections, subsubsections, subsubsubsections, and
		achapters use the section fonts.

In addition, there are a number of places where the macro
package will use big_font, etc., itself.  These are mentioned
in the appropriate sections later.  The default values for the
registers listed above are set when you read in R.MACROS, but
only if you have not previously set them.  Further, the default
values are set according to the values of normal_font,
bold_font, etc., in effect at the time you read in R.MACROS.

This node describes how to type in arguments to macros.  Both
normal macro invocation (with "." and ' at the beginning of a
line), and inline macro invocation (with ^X) are discussed.
Note that most of the nice features of the macro package come
to you as macros, so it is important to know how to use them.

General information:

	All macro invocations consist of the NAME of the macro
to invoke, and zero or more MACRO ARGUMENTS, supplied after the
macro name, in order.  The effect of a macro invocation is to
cause some previously defined sequence of R commands to be
processed, very similar to .SO or ^S or ^N.  The macro
arguments are available to these commands (via the ^A control
character).  Further discussion of exactly how it all works
appears in node Writing Macros.

Normal Macro Invocation:

	A normal macro invocation takes one of two forms:

	.macro-name arg0 arg1 arg2 ... argN
or	'macro-name arg0 arg1 arg2 ... argN

There may be any number of spaces and tabs between the "." or '
and the macro name.  Then zero or more arguments follow.  There
are several forms that may be used to express an individual
argument:

Form 1:  The argument is simply written down.  This is the
easiest form to use, and the most common.  However, it has some
limitations.  You cannot have an unprotected control-space or
control-tab in this form of argument (because spaces and tabs
are used to separate arguments), or an unprotected control-J
(newline) (because newlines terminate the whole macro
invocation line).  So, you must either protect such characters
with backslash (see node Backslash), or, in the case of spaces,
you could use a text space or a character that translates to
text space.  Nodes Input and Justification explain this in more
detail.

Form 2:  The argument is surrounded by double quote characters
(").  This form of macro argument may control unprotected spaces
and tabs, but cannot contain an unprotected control-J (newline).
Also, to get a " character in as part of the argument, you must
write two quote marks in a row.  For example, .foo """" invokes
foo with a single argument consisting of the single character ".
Here is another example of a form 2 argument:
	.chapter "Effects of Swapping on System Performance."

Form 3:  The argument is surrounded by { and }.  This form of
macro argument may contain unprotected spaces, tabs, and
control-J's, and is therefore the only form of argument that
can extend over more than one input line without special care.
Its only limitation is that the curly brackets, { and }, must
be BALANCED inside the argument.  If an argument of this form
extends over too many lines, an error message is printed (to
help you find unmatched curly brackets).  See the reference
manual for details.  Here is an example of this form of macro
argument:
	.chapter {Effects of Swapping on System Performance.}

Inline Macro Invocation.

	An inline macro invocation one of these forms:
	^Xmacro-name
or	^Xmacro-name!
or	^Xmacro-name(arg0 arg1 ... argN)

The first and second kinds are used when the macro is to be
supplied no arguments at all.  The ! can be used all the time,
and must be used in cases where the next character read might
be included in the macro name.  See node registers for further
discussion and example of this use of !.  The last form is used
when the macro has 1 or more arguments.  The forms the
arguments may take are essentially the same as the forms for
normal macro invocation, which are listed above.  There is only
one difference: you may not have unbalanced parentheses in an
argument of form 1.  What actually happens is that every time
an open parenthesis is seen, the argument scanning continues at
least until the matching close parenthesis.  This permits
nested use of ^X, as shown here:
	^Xdiv(a+b ^Xdiv(c d*e))
The arguments to the first invocation are "a+b" and "^Xdiv(c d*e)",
and the arguments to the second invocation are "c" and "d*e".

Differences between the two kinds of macro invocation.

	The main difference between the two forms is that
normal macro invocation may be used anywhere, and takes effect
immediately, whereas inline macro invocation only takes effect
when the ^X is seen when scanning text (as opposed to reading
request lines).  Another important difference is that any text
produced by inline macro invocations is automatically glued to
surrounding words (assuming they are adjacent).
	Most of the macro in the macro package are designed to
be invoked using normal macro invocation.  Others are intended
to be invoked inline, and explanations of them will mention
that fact.  Do not expect good results if you invoke a macro in
a fashion other from that intended for it, because the
principles of design of the two kinds of macros are a bit
different.

The standard macro package splits each output page up into a number of
regions, from top to bottom.  These are:

	the header area
	the text area
	the footer area

We describe each in turn, and at the end, introduce some
convenient macros used for setting up margins, and explain R's
notation(s) for vertical distances and their meanings.  We also
mention miscellaneous requests used for vertical positioning.

Headers:

	Headers are things like the page number, etc., printed
at the top of each page.  The default is to print "- page# -"
centered at the top of the page.  The string registers
left_heading, center_heading, and right_heading contain the
actual headings, so you can change them freely.
	The number register section_headings, if set to 1 (it
is normally 0) will set left_heading to the contents of
section_title, and right_heading to the contents of
section_number_title, for each page.  See node Sectioning for
details of what those registers contain.  (Section_title is the
title of the current section, and section_number_title is
something like "Section 1.3".)
	The number register both_sides controls whether to swap
the headers on pages with even numbers.  It is defaultly off
(0), but you should set it to 1 for documents to be reproduces
by printing on both sides of the paper.
	Headers are normally suppressed on the first page (page
1), but if you set the number register print_page1_headings to
1, then they will be printed.  If you want no headings at all,
set the number register print_headings to 0.  The number
register heading_font control what font will be used to print
the headings (defaultly normal_font).
	The number register heading_pos contains the vertical
position at which to print the headings (if any).  This is
expressed in mils (thousandths of inches), measured from the
top of the page.  Thus, the default value, 500, print the
headings 1/2 inch from the top of the page.  If it makes a
difference, the distance is from the top of the page to the
baseline of the header line.

Text area:

	The text area starts below the headers.  The exact
position is controlled by the number register top_margin_size.
Thus, according to R, the headers are printed in the margin.
The default value for top_margin_size is 1000, and its units
and meaning are like those of heading_pos, so text normally
starts one inch from the top of the page.
	The text area end just above the footers.  The distance
from the end of the text area to the end of the page is defined
by the number register bottom_margin_size, and is defaultly
1000 (i.e., one inch).  Note that figures, tables, and
footnotes are always printed in the text area, even when
printed at the bottom of the page.  For more details on them,
see the relevant node.

Footers:

	Footers are like headers, except they are printed at the
bottom of the page.  Their appearance is controlled by number
and string registers analogous to the ones for headings; we
simply list them below, and indicate the default values:

	print_footings - 0 (i.e., normally NOT printed)
	footing_font - normal_font
	left_footing, center_footing, right_footing - string
		registers, all normally empty
	footing_pos - 500 (mils, measured from top of bottom
		margin, i.e., end of text area)
	footing_height - 167 (mils, increase it if you use a
		large font; its purpose is too obscure to go
		into here)

The number register both_sides controls swapping of footers as
well as headers.  Footers will be printed on page 1 (if
print_footings is on (1)).

Setting margins:

	You could set up all the margins yourself, and for
complicated things, you maybe required to do that.  But there
are two macros available that handle most of the common cases.

The old macro:  MARGIN

	This macro takes four arguments, each suitable for a .VX
(see description of vertical units and requests, below), in this
order: top margin size, bottom margin size, left margin size,
and right margin size.  Note that headers are printed WITHIN the
top margin, and footers within the bottom margin.  Also, this
macro does NOT change heading_pos or footing_pos, or take
both_sides into account.  The macro described below is probably
better -- MARGIN is being retained for compatibility.
	This example sets the margins to the way they start:
	.margin 1i 1i 1i 1i

The better macro:  SMARGINS

	This macro takes four to six arguments.  The first four
arguments are the top, bottom, left, and right margin sizes, in
that order, however, the top and bottom margin sizes indicate
the amount of white space desired.  That is, headers and
footers will not be printed in these margins.  The fifth
argument, which is optional, allows you to specify the distance
between the headers and the start of the text area (defaultly
1/2 inch) and the sixth argument (also optional), can be used
to specify the distance from the end of the text area to the
footers.
	This macro takes the settings of print_headings and
print_footings into account, so as to provide the maximum text
area that is consistent with the margins requested.  That is,
if you do not print headers (footers), then the space that
would otherwise be used for them will be used for text.
	SMARGINS also takes both_sides into account when
setting up the left and right margins.
	This example sets the margins to the way they start:
	.smargins .5i .5i 1i 1i .5i .5i

Vertical expressions:

	A vertical expression consists of a whole number, or a
number with a decimal fraction, optionally followed by a
letter.  here are the different meanings for the letters;
assume the number was "n":

	no letter - n times the default line height; the default
		line height is directly related to the height
		of the principal font.  For details see node
		Line Spacing.
	a - n micas.  One mica = 10 microns = .01 centimeters =
		1/2540 inch.  Because a mica is less than a mil,
		conversions to/from micas may not be exact.
	c - n centimeters.
	i - n inches.
	l - n lines.  This is like n with no letter, except that
		it is additionally multiplies by the line
		spacing factor, LS.  See node Line Spacing for
		more details.
	m - n mils.  1 mil = 1/1000 inch = 2.54 micas.
	u - n units, where a unit is the smallest distance by
		which the output device can position text
		vertically.  This should be avoided because it
		introduces dependencies on particular devices.
		It is included because it is sometimes necessary.

In situations calling for a vertical expression, you may use
any of these freely.  For example, the .SP request takes a
single argument, a vertical expression, so all of the following
are legal:
	.sp 1
	.sp 1l
	.sp 2.5c
	.sp 135u
	.sp .5i
	.sp 150m
	.sp 650a
More complicated expressions are permitted, too.  See node
Expressions for details and examples.

Relevant requests:

	.VX n v1 v2 v3 ... vK - set the number register n to be the
		number of mils in the sum of the distances given
		by the vertical expressions v1, v2, ..., vK.
		For example, .vx vpos vpos!m 10l
	.VV n v1 v2 v3 ... vK - equivalent to:
		.NV n n
		.VX n v1 v2 v3 ... vk
	.SP v - leave an amount of white space equal to the
		vertical distance specified by the vertical
		expression v.  A blank line is equivalent to a
		.SP with no arguments, which is equivalent to
		.SP 1
	.VP v - go to position v on the page.  0 means the top,
		1i means one inch from the top, etc.

	Some other relevant requests are described in Line
	Spacing.  Also, ^V(+v) and ^V(-v) are described in Line
	layout.  The reference manual section on line spacing
	discusses this in more detail, including the VPOS and
	LVPU number registers.

NOTE:  1i in a vertical expression is not equivalent to 1i in a
horizontal expression, because horizontal items (e.g., HPOS)
and vertical items (e.g., VPOS) are stored internally in
different units.

There are several factors that control the space between lines
in R.  They are:
	the height of the principal font
	the leading
	the line spacing factor (LS)
and	the actual height of the line

The nominal spacing between consecutive output lines is the
DEFAULT LINE HEIGHT times the line spacing factor LS.  That is,
the distance between the baselines of two lines will be:
	default line height * ls / 100
The division by 100 is there because LS is in units of
hundredths of line heights.  In vertical expressions, the
number n means n times the default line height, whereas nl (n
lines) means n times the default line height times the line
spacing factor.

The default line height is defined this way:
	default line height = fheight * (100 + leading) / 100
where fheight is the height of the principal font (the distance
from the bottom of the character that goes the farthest below
the baseline to the top of the character that goes the farthest
above the baseline).  FHEIGHT is available in the number
register of the same name, as is LS.  The number register
LEADING gives the default percent white space between lines, and
starts as 20.  This choice is governed by long established
aesthetic principles of the printing industry, so you should not
change it lightly.  The appropriate place to make an adjustment
is usually LS, and R provides the .LS request for that purpose.
Note that .LS takes the line spacing factor "straight", so that
the value of the LS number register is 100 times the value you
write in a .LS.  For example, .ls 2 will give you double spaced
output.  R starts with LS equal to 100 (single spacing).

Historical note:  Leading is pronounced "ledding", and refers to
the fact that in printing the space between lines in filled with
thin strips made of lead.

The above discussion concerns the NOMINAL spacing of lines.  R
calculates the exact height of each line above and below the
baseline (the HABOVE and HBELOW built-in number registers
provide access to this information), and R will move a line down
to make sure that it does not overlap the previous line.  This
happens more often if LEADING is set to a smaller value, or if
you use a lot of subscripts, superscripts, or characters from a
large font.  If you do not like it, your only recourse is to
increase the line spacing, or get rid of the offending tall
character(s).

R divides the space across the output page into a number of
regions, from left to right:

	the left margin
	the indentation
	the text area
	the right indent
	the right margin

The sizes of these are defined by the values in various number
registers, and can be controlled by setting the number
registers or using some R requests.

Below is a description of the interesting things in left to
right order.  At the end is a description of horizontal
expressions.

	Left margin - Defined by what is called the OFFSET,
which may be different for even and odd numbered pages, so that
document to be reproduced on both sides of the paper can be
handled nicely.  This can be examined via the EO, OO, and POFF
number registers, but can be set only via the .EO and .OO
requests.  The default is one inch for both even and odd
offsets.  For more details on changing margins, see the
discussion near the end of node Page Layout.

	NOTE: The offset defines the origin of horizontal
position calculations, specifically, HPOS is 0 when you are at
a distance from the left edge of the paper equal to the offset.
Also, the horizontal position is never permitted to be less
than 0.

	Indentation - The indentation is defined by the value
of the INDENT number register, and is the distance from the
offset to where the current text line should start.  The
indentation is typically 0, but it is not unusual to indent a
group a text lines, as in the case of a quotation, for example.
If you want a number of indented items, you may find the list
macros convenient; see node Lists for more information about
them.  The indentation can be changed "manually" with the .IN
request.  This takes three forms, illustrated below:
	.in 1i		set the indentation to one inch
	.in +1i		increase the indentation by one inch
	.in -1i		decrease the indentation by one inch
Usually a matched pair of the last two forms is better than
setting the indentation explicitly, because it allows something
to be moved around, etc., with fewer errors.  Node Alignment
discusses a very safe and easy to use method changing the
indentation, which you should read about.
	In addition to the indentation, which is used for
indenting a group of lines, there is also a feature called the
TEMPORARY INDENTATION, which takes effect for just the next
line.  It can be set only via the .TI request, which has three
forms just like those for .IN.  Note that a relative temporary
indentation is relative to the indentation.  This request is
often used for making paragraphs, e.g.:

	.de para	define a macro for starting a paragraph
	.  sp 1l	it will first leave a blank line
	.  ti +5	and then indent the first line by 5 characters
	.  em

	Text area - The text area extends from the indentation,
plus any temporary indentation, to the right indentation.
Thus, the actual length of the text area is defined implicitly.

	Right indentation - The right indentation is the
distance from the right margin to the end of the text area.
Increasing the right indentation makes the text area smaller;
that is, the indentation and the right indentation are both
measured toward to center of the page.  The right indentation
is controlled by the number register RINDENT, which may be set
directly, or via the .IR request, which works just like the .IN
request.  The right indentation starts as 0.

	Right margin - The right margin is defined implicitly
by the offset and line length.  That is, the right margin
starts at that place which is the offset plus the line length
from the left edge of the paper.  For 8.5 inch wide paper, and
the default offset (1 inch) and default line length (6.5
inches), the right margin will be 1 inch.  See node Page Layout
for descriptions of two macros to assist in setting up margins.
The line length is defined by the number register LL, and can
be set directly or via the .LL request.

Horizontal expressions:

	Horizontal expression are very similar to vertical
expressions.  A horizontal expression consists of an expression
(see node Expressions), possibly followed by a letter to
indicate a unit of measurement.  Here are the possibilities,
assuming the value of the expression is n:

	no letter - n times the average character width.  The
		average character width is the width of the "0"
		character, unless it is less than the width of a
		space (in which case the width of the space is
		used), or greater then the width of two spaces
		(in which case the width of two spaces is used).
		The font used for this is the principal font,
		NOT the current font.
	a - n micas
	c - n centimeters
	i - n inches
	m - n mils

There are .HX and .HV requests that are analogous to the .VX
and .VV requests discussed in node Page Layout.  You should
NEVER use .HX or .HV to compute a vertical distance, or .VX or .VV
to compute a horizontal distance, because the internal units
may be different.  For example, on the XGP the units are XGP
dots, and there are 192 per inch horizontally, but 200 per inch
vertically.  Even though R gives you the measurements in mils,
it uses these units internally, so you must not confuse the two
directions.

There are several sub-topics here; you should definitely read
the first two.  Also, you should have read node Line Layout
first.

The current horizontal position is determined by the value in
the number register HPOS.  It is measured from the offset (the
right edge of the left margin), and increases to the right.
Outputting text and spaces or tabs increases the horizontal
position by the width of the characters output.  (For details on
tabs, see node Tabs.)  There are three ways to set the
horizontal position to a particular value:

	set HPOS, with .HX or .NR
	use ^P
	use .HP

Setting number registers should be familiar to you (see node
Registers).

	.HP h
will set the horizontal position to h (h is a horizontal
expression; see nodes Line Layout and Expressions.)  You may
also say:
	.HP +h
	.HP -h
to increment or decrement the horizontal position by h.
However, if you are thinking of doing that, you probably should
be using relative positioning (see node Relative Positioning).

	^P(h) also goes to position h (h is a horizontal
expression here), with a difference, though.  It always moves
right by at least the width of a space, and gives an error
message if the position you asked for is to the left of where
it ends up.  Thus, it prevents overprinting, and cannot be used
for going backwards.

If you are trying to get things on different lines to line up,
read node Alignment.

Some details:

Any absolute positioning command (tab, ^P, .HP, or setting
HPOS) suppresses BOTH mode adjustment on its left.  The main
implication of this is that absolute positioning is usually
inappropriate in the middle of a line in fill mode.

The value of HPOS corresponds to where you are now, not where
you would be after the line is adjusted.  (The latter would
require predicting the future.)  Therefore, the value of HPOS
is not necessarily useful when the adjustment mode is anything
but LEFT mode.

The .HS request (HS = horizontal space) is used for relative
positioning.
	.HS h
goes forward (or backward if h is negative) the amount
specified by the horizontal expression h.  Unlike .HP and
friends, this works in fill mode.  Further, although R may
break a line at an absolute position command, it will never
break a line at a .HS.  So, .HS is the method of choice for
building up formulae and expressions like this:
	|A|
	 U  a
	i=1  i
However, before embarking on doing such things by hand, read
node Math -- it will tell you about the macros already there to
help with this sort of thing.

R has a built-in tab stop mechanism that lets you set a large
number of tab stops.  The R control character control-I (tab)
goes to the next tab stop, if any.  (It always moves over at
least one space width.)  These are the requests available for
manipulating tabs:
	.ta h1 h2 ... hn - Removes all existing tab stops, and
		sets stops at the positions specified by the
		horizontal expressions h1, h2, ..., hn.  R
		starts with a dozen or so stops set at intervals
		of 8 characters.  That is, .ta 8 16 24 ...
	.tg name exp - Number register "name" is set to the
		position of the exp'th tab stop.
	.tu h - "Unset" (clear) any tab at position h.
	.ts h - Set a tab stop at position h.
See the reference manual for more details.

Note:  The normal tab stops are set by character positions,
which, if you remember, are defined by the nominal width of the
principal font, which may not be the current font.  So do not
expect a tab to be 8 spaces in the current font unless you do
this:
	.fs n   -- makes the font both the principal and current font
	.rtabs  -- does a .ta 8 16 24 ....
Of course, even this will not work if you are using a variable
width font.  If this is a problem, read node Alignment.

The actual action caused by ^C and ^R is to center or
right-flush the following text between the first absolute
positioning command on the left and the first one on the right.
For this purpose, the margins constitute absolute positioning
commands.  In this case, the margins include any indentation,
temporary indentation, or right indentation.  Thus, the
position of centered text will be different for different
values of INDENT.

Between any adjacent pair of absolute positioning commands, you
may have centered items, right-flushed items, or both.  The way
you write it down goes like this:
	pos1 left adjusted items^Ccentered items^Rright-flushed items pos2

Before trying to make up fancy tables by hand, you should read
node Columnar Tables.  It describes macro packages that make it
a lot easier for you.

There are many interesting things you can do in text.  We have
gathered together here the ones that are not discussed elsewhere.

Superscripting and subscripting are special cases of changes to
what is called the VERTICAL OFFSET.  The vertical offset is
controlled by the number register VOFF, and is the distance
above the baseline at which output characters are to be placed.
It is normally 0, meaning characters will be placed on the
baseline.  Making VOFF greater than 0 causes subsequent output
to be above the baseline, and making VOFF negative, outputs
characters below the baseline.  Although it may be a little
confusing, VPOS, the current vertical position (which
determines where the baseline is) increases DOWN the page,
whereas VOFF increases UP the page.

Here are the methods available for adjusting the vertical
offset:
	setting VOFF - generally used only in macros
	^U - up: increase VOFF by a device dependent amount
		(set so that it looks good for superscripts)
	^D - down: decrease VOFF by the same amount that ^U
		increases it; good for subscripts.
	^V(v) - Change the vertical offset by v; v is a
		vertical expression (see nodes Page Layout and
		Expressions).  The change may be positive or
		negative.
	^Z - set the vertical offset to 0.

Here are some examples:
	a^Di^U	- a subscript i
	x^Un^D  - x superscript n
	m^Di^Dj^U^U - appears something like this:	m
							 i
							  j
^U and ^D should always be used in matched pairs.  If the
vertical offset is not 0 at the end of an output line, R will
print a warning message, going something like this:
"unterminated superscripts" (or subscripts).

Likewise, ^V should be used in matched pairs of ^V(+...) and
^V(-...) to avoid the same error.  When setting VOFF directly
you must remember to set if back.  Also, you should keep in
mind that relative adjustments (e.g., .nr voff voff+10) can
more easily be included in larger formulae than absolute ones.
Hence, we do not recommend the use of ^Z.

In addition to using the control characters directly, there is a
(possibly somewhat more convenient) pair of macros for doing
superscripts and subscripts.  Here is how to use them:

	^Xsub(item1 item2 ... itemN) - will output the N items
	shifted down by one ^D, and automatically shift back up
	when done.  Further, it guarantees that there will be no
	line breaks in between the items.

	^Xsup(item1 item2 ... itemN) - works exactly the same
	way, except that it output the items shifted up.

Here are some little examples:

	a^Xsub(i)		-- a
				    i

	a^Xsub(i^Xsub(j))	-- a
				    i
				     j

				    n
	x^Xsup(n)		-- x

				      2
				    (n )
	x^Xsup((n^Xsup(2)))	-- x

(These would look better on the XGP or Dover.)

If you are trying to think of ways to build up more complicated
mathematical formulae, you should read node Math for a detailed
discussion.

Here is a list of the various things about underscoring thAt
are under your control:

	whether underscoring is being done
	whether white space is to be underscored or just text characters
	the position of the underscoring with respect to the baseline
	the thickness of the underscore

The number register UL controls whether underscoring is
currently being done (0 means no underscoring, 1 means
underscoring).  However, the most common way of doing
underscoring is with control characters:

	^B - begin: start underscoring (set UL to 1)
	^E - end: stop underscoring (set UL to 0)

For example:

	The third ^Bword^E in this sentence will be underscored.

The number register UL_SPACE controls whether white space will
be underscored, or just text characters.  If it is 0, only text
will be underscored; if it is 1, white space will be, too.
Note: if a text character prints as white space (e.g., a text
space usually does), then it will be underscored in any case.
Remember: R does not know anything about the appearance of text
characters.  UL_SPACE starts set to 0, so white space is
normally NOT underscored.

The position of underscoring with respect to the baseline is
determined by the underscore offset, which is kept in the
number register UOFF.  It is measured in the same fashion as
VOFF (see node Superscripting and Subscripting).  It starts
with a device dependent value that gives underscoring with a
pleasing appearance.  You may change the underscore offset by
setting UOFF directly, or by using the .UO request, documented
in the reference manual.  Generally the only good reason for
changing the underscore offset is to draw a horizontal line, as
in the DIV macro (see node Math).  Naturally the fineness with
which UOFF can be adjusted depends on the capabilities of the
output device.

The thickness of underscoring is initially set to a pleasing
value (device dependent).  You may change it with the .UT
request, documented in the reference manual.  Of course, not
all output devices support this feature.

R provides the ability to print more than one character in the
same position, and thus overstrike.  This can be used to create
new symbols (similar to the way APL overstrikes, for those of
you familiar with that), and also permits you to add
diacritical marks such as the French accent ague, accent grave,
and circumflex ("hat").  Here is a description of the feature.

As R accumulates a word, character by character, you can think
of there being a row of boxes.  Normally R places one character
in each box, from left to right.  However, the control
character ^H (backspace) directs R to back up one box.  By
backing up and then adding more characters, more than one
character may be placed in each box.  When it comes time to
print the word, R examines each box in turn, and prints its
contents.  The exact method of printing the contents of one of
the boxes is to print each of the characters of the box
centered in a space equal to the width of the widest character.
Hence, even if you back up several boxes by using more than one
^H, the characters in that box will still line up.

NOTE: ^H works only WITHIN a single text word; you cannot back
up over (control) spaces, or positioning commands, etc.  If you
are considering using ^H for multiple characters, you should
probably be thinking of using .HS (see nodes Horizontal
Positioning and Alignment) or some of the convenient macros for
mathematical formulae (see node Math).

HINT:  A string register is a convenient way of "abbreviating" a
special symbol that requires several characters to print.  For
example:
	.sr ne =^H/
	.sr ahat a^H^
This method has the additional advantage that if you later
change your mind about how to make the special symbol (e.g.,
you find a font that has it), you need change only yhr register
definition.  Further, string registers are the only way to go
when the symbol must be constructed in different ways for
different output devices:
	.if lpt
	.  sr ne =^H/
	.else
	.  sr ne ^F6^Q^R^F*
	.  end if

R does not provide an automatic hyphenation facility.  However,
it does provide two control characters to assist in manual
hyphenation:
	^Y - Insert an invisible hyphen here
	^W - A word break is legal here
An INVISIBLE HYPHEN produces no output unless R break the output
line at the ^Y, in which case it prints as a hyphen ("-").
Thus, it can be inserted in a word that you wish to have broken
to improve the appearance of a given output line.  Using ^Y is
better than inserting a hyphen by hand because ^Y will continue
to do the right thing even if you change the document around
later such that the word in question no longer falls at the end
of an output line.  Here is an example use:
	hyphen^Yation

^W is similar, but is intended for words that already have a
hyphen in them:
	ambassador-^Wat-large

Generally people do not use ^Y and ^W much, but insert them
only in places where they are really needed.  Of course, you
usually cannot tell that a break is needed until you have
printed your document.

R provides a very general and powerful facility for substituting
arbitrary strings for single characters in the output.  This can
be used to do a number of things; here are some examples:

	You can have a convenient to type character translated
	into one that is inconvenient to type, and thus make
	your typing easier.

	You can "fix" a character, e.g., move it up or down a
	little before printing it, or substitute a character
	from another font.

	You can have a character turn into an inline macro
	invocation that generates exactly what you want;
	similarly, you could have the character insert a string
	register, or directly come several characters.  A
	specific example might be translating something to =^H/
	so it looks like a "not equal" sign.

	You can translate a character into a control character,
	to avoid any special meaning of the control character
	until it is actually output.  (We present a specific,
	very useful example below.)

We now describe what is available, and give some examples.
Substitution, also known as OUTPUT TRANSLATION is controlled by
the .TR and .TC requests:
	.tr c s
	.tc f c s
Each causes occurrences of a TEXT character "c" to be replaced
by the string "s".  .TR does it for all fonts; .TC does it only
for the font "f".  ("f" is a single character font designator.)
.TR translations are performed first, and then .TC ones.  In a .TR,
if the string "s" is omitted, it is assumed to consist of a
single character: a text space.  Thus, the line
	.tr @
that occurs in the example setup file in node Setup, causes
occurrences of @ in text to be changed to text spaces.  That
particular use of .TR is the most common.

Output translation does not occur until just before the
character would be assembled into a text word.  In particular,
it does not happen to anything on a request line.  This fact
can be used to advantage.  For example:
	.tr ` \           (Translate backquote to control-space)
can be useful in that it makes expression of macro arguments
and other things easier by giving you a character that
eventually becomes a text space, but does not appear as a text
space when macro arguments are being scanned.  Here is an
example used:
	.chapter Suggestions`for`Further`Research.
I have found this particular translation to be useful in case
where I do not want my text editor to break a line (I usually
have it set in a mode that breaks long lines as I type them).
For example:
	^Xital(This`is`some`text`in`italics.)
This is useful because inline macro invocations (^X) cannot
span more than one input line.

Suppressing Translation:

	Doing ".tr @" is all well and good, but how can I ever
print a real @ character?  You could turn the translation off
and back on:
	.tr @ @
	....@.....
	.tr @
Note that .TR and .TC special case the translation of a
character to itself to mean to remove any translation of the
character in question.
	There is an easier way to suppress translation in
particular instances, however.  The control character ^O
suppresses any translation of the next text character.  Thus,
"^O@" will cause a real @ to be printed when you have done
".tr @".

NOTE:  The characters substituted in an output translation are
themselves subject to further translation.  (Translation is
implemented by gobbling the output character and making it look
as if you had really typed the substituted string.)  So, if you
did this:
	.tc 5 $ ^V(-10m)$^V(+10m)
in an attempt to shift the $ character of font 5 down 10 mils,
you would bomb out, because the new $ will be translated, too.
What you should say is:
	.tc 5 $ ^V(-10m)^O$^V(+10m)

Input translation:
	R does not have a complete input translation facility.
For what is available, see node Input, or read up on the .CC,
.NC, and .EC requests in the reference manual, as well as the
discussion of the input mapping, etc.

This node discusses how to get things on different lines to
line up vertically.  We assume that you are familiar with the
material in nodes Line Layout and Horizontal Positioning.
There are several different methods you can use; we outline
them below, calling attention to their advantages and
disadvantages for particular situations.  We suggest that you
read about all of them, because each is good in different
cases.

Method 1:  Guessing.  Sometimes just putting in spaces and tabs,
or "eyeballing" a distance can produce reasonable results, but
don't count on it.  In particular, when using spaces and tabs,
items on different lines will line up only if you are using a
fixed width font, and you set the tab stops to 8, 16, 24, ...,
while the font in question is the principal font.  For example:
	.fs n     -- make the font both the principal and current font
	.rtabs    -- a macro in the standard package that sets a
		lot of tabs at the requisite intervals (8, 16, 24, ...)
In the case of a fixed width font this method works well because
the "guessing" has become exact.

Method 2:  Logical Tab Stops.  In addition to the built-in tab
mechanism of R, the macro package provide a somewhat different
mechanism, which, unfortunately, also goes by the name of tabs
and tab stops.  To tell the two apart, we have introduced the
term "logical tab stop" for the kind of tab stop implemented in
the macro package.  A logical tab stop is name for a place
across the page.  Here are the main macros involved (we
illustrate how you invoke them):

	^Xs(name) - sets the logical tab stop called "name" so
	that it "remembers" the current horizontal position.
	This is implemented like this:
		.de s
		.  nr tab_pos\^A0 hpos
		.  em

	^Xt(name) - Go to the place remembered by the logical
	tab stop called "name".

	^Xp(name) - Just like ^Xt(name), except that it uses ^P,
	so it never goes backwards, and prints an error message
	if you try.

	^Xbtab(name) - Just like ^Xt(name), except that it does
	a line break first (i.e., it starts a new line).

Here is an example.  Say that you want your output to look like
this:		foobar (arg1,
			arg2,
			arg3)

Here are two ways to do it with the macros given above:
		foobar (^Xs(1)arg1,
 ^Xt(1)arg2,
 ^Xt(1)arg3)

		foobar (^Xs(1)arg1,
^Xbtab(1)arg2,
^Xbtab(1)arg3)

Here are some things you should notice:

	When using ^Xp or ^Xt at the beginning of a line, it is
a good idea to precede them by a space.  This forces a line
break.  Otherwise the tabbing may be attempted on the previous
line.  ^Xbtab solves this problem.

	The argument to the ^Xs, ^Xt, etc., macros can be any
string of characters so long as it can be part of a register
name.  (These characters are A through Z (case not
distinguished), 0 through 9, and _; for more information, see
node Registers.)

Method 3:  Indentation.  If the kind of alignment you desire is
to have several lines all start at the same place, the
indentation may be the most convenient thing for you to use.
Node Line Layout has a detailed explanation of the indentation
and how to change it.  However, the macro package provides some
macros that can help you:

	.align name  - Set the indentation to the position
	remembered by logical tab stop "name".

	.unalign - Return to the previous indentation.

	^Xa(name) - Has the same effect as doing ^Xs(name) and
	then ".align name", but happens all at once, and can be
	used in-line.

The earlier example could be expressed with these macros as
follows:	foobar (^Xa(1)arg1,
arg2,
arg3)
.unalign

This should be done in nofill mode; or else you could put a .BR
after each line, to force it out.

The ^Xa and .align macros can be nested, as illustrated here:

	foobar (^Xa(1)arg1,
ralph (^Xa(2)inner-arg1,
inner-arg2),
.unalign
arg3)
.unalign

Additional Features:

	For fancier alignment, such as different parts of
formulae, expressions, or equations, see node Math.  For
outputting column oriented tables, see node Columnar Tables.

	^Xc(name item1 item2 ... itemn) - will output the
items, separated by spaces, centered about the logical tab
position called "name".  Naturally you must do a ^Xs(name)
sometime before doing this.

The standard macro package provides considerable assistance in
structuring a document into sections such as chapter, sections,
and appendices.  For processing a large document in separate
pieces, see the macro package in R;SECT RMAC (it has its own
instructions at the beginning of the file).

The kinds of sections supported by the standard macro package
are:
	chapters
	sections
	subsections
	subsubsections
	subsubsubsections
	appendices
	achapters	(chapters within appendices)

These have the following nesting relationships:

	subsubsubsections are part of subsubsections
	subsubsections are part of subsections
	subsection are part of sections
	sections are part of chapters, achapters, or appendices
	achapters are part of appendices

Note:  There is a flag (number register) called achapters,
which says whether to use achapters or not (0 means no
achapters, 1 means achapters are all right).  If achapters is
1, then sections may not be part of appendices, but may be part
of achapters.  If achapters is 0, then achapters should not be
used at all.

Here are the available macros:

	.chapter
	.section
	.subsection
	.subsubsection
	.subsubsubsection
	.appendix
	.achapter

Each of these starts a section of the indicated kind.  Each of
the macros takes a single argument, the name of the section.
For example:
	.chapter "Suggestions for Future Research."
The current chapter number, section number, etc., are managed
automatically.  They are available in these number registers:

	chapter, section, subsection, subsubsection,
	subsubsubsection, appendix.

In every case these are the numbers of the CURRENT section, and
are incremented when you define a new section of that kind.
For example, before any .chapter's, the chapter number register
will be 0; the first .chapter increments it to 1, etc.  Also,
when a sectioning macro is invoked, the counter for the next
smaller kind of section is set to 0.  For example, .chapter
sets section to 0.  In sum, the numbering is done the "right
way", with numbers always starting at 1.  Of course, you can
change the numbers freely.  For example, if for some reason you
want the first section in some chapter to be numbered 0, just
set section to -1 after the .chapter and before the first
.section.

Note: The chapter number register is used to number the
achapters in an appendix, if you are using achapters.

The sectioning macros have two main effects:

	A header line is produced.
	A line may be added to the table of contents.

For details about the table of contents, see node Table of
Contents.

The different things you can control about the header line are:

	The space produced before the line;
	the amount of the .NE before the line;
	the font used for the line;
	the form of the header line itself;
	the space produced after the line.

Most of these are controlled by string registers, and in most
cases there is one register chapter_... that controls the value
used for chapters, appendices, and achapters, and one register
section_... that controls it for sections, subsections, etc.
Here are the various STRING registers, and their default
values:
	chapter_space_before 1		(.sp ...)
	section_space_before 1		(.sp ...)
	chapter_need 5l			(.ne ...)
	section_need 4l			(.ne ...)
	chapter_space_after 1		(.sp ...)
	section_space_after 1		(.sp ...)

	chapter_form		\^Ssection_number.  \^Ssection_title
	section_form		\^Ssection_number  \^Ssection_title
	subsection_form		same as section_form
	subsubsection_form	same as section_form
	subsubsubsection_form	same as section_form
	appendix_form		^C\^Ssection_number_title - \^Ssection_title
	achapter_form		same as chapter_form

The string register section_title is always set to the title of
the section, namely, the argument to the sectioning macro.  The
string registers section_number and section_number_title are a
bit more complicated, and we will talk about them in a minute.

The font used for the header line is controlled by a NUMBER
register:
	chapter_font  big_font
	section_font  normal_font

Now, here is how the section_number string register is set by
the various macros:

	chapter - \^Nchapter
	section - \^Schapter_number.\^Nsection
	subsection - \^Schapter_number.\^Nsection.\^Nsubsection
	subsubsection, subsubsubsection - similarly
	appendix - \^Schapter_number
	achapter - \^Schapter_number

And here is how the chapter_number string register is set by the
relevant macros:

	chapter - \^Nchapter
	appendix - \^N:appendix		(Roman numerals: I, II, III, ...)
	achapter - \^N:appendix.\^Nchapter

Lastly, here is how section_number_title is set by the relevant
macros:

	all except appendix - Section \^Ssection_number
	appendix - Appendix \^Ssection_number

Other details:

	Chapters normally start on a new page, but this is
controlled by the number register chapter_starts_page.  If it
is 0, then a new page will not be started for each chapter; if
it is 1 (it starts as 1), then a new page will be started.
Part of this process is the forcing out of any figures,
footnotes, etc., for the previous chapter.  Appendices always
start on a new page, and achapters never do.  The appropriate
way to start a new section at the top of a page is to do:
	.top_of_page
If you want any pending figures, etc., output first, do a
	.force_out
before the .top_of_page.  These macros interface more smoothly
with the macro package than .BP, for example.
	Before going on, here are a few comments about .BP, .PN,
and the PAGE and NEXT_PAGE number registers.  PAGE always
contains the number of the current page, and NEXT_PAGE always
contains the number of the next page to be output.  Setting
NEXT_PAGE does not affect PAGE, but any time PAGE is set,
NEXT_PAGE is set to one plus the new value of PAGE.  For
example, .NR PAGE 103 will set NEXT_PAGE to 104.  If for some
reason you stack and unstack PAGE with .NV, both the stacking
and unstacking operations set PAGE, and therefore change
NEXT_PAGE.  .BP sets NEXT_PAGE to its argument, if any; then it
sets PAGE to NEXT_PAGE; finally it causes a new page to be
started.  .PN merely sets NEXT_PAGE; .NR NEXT_PAGE works just as
well.  As mentioned above, it is suggested that you use
.top_of_page instead of .BP; but .PN is all right.

	Normally, page numbers increase throughout the
document.  However, you can optionally number them on a
per-chapter basis, which causes the page number to be reset to 1
at the start of each chapter.  This feature is controlled by the
number register pages_per_chapter: if it is 0, pages are
numbered normally; if it is 1, pages are numbered per-chapter.
Almost all places in the macro package print the page number by
inserting the string register page_number, which is set as
follows:
	normal page numbering:  \^Npage
	per-chapter numbering:  \^Schapter_number-\^Npage
Of course you can change it if you wish.  Note that when
per-chapter numbering is used, pages before the first chapter
will have page numbers like 0-1, 0-2, etc.

	Similarly, figure and table numbers increase throughout
the document, unless you set figures_per_chapter to 1, and then
they will be numbered per chapter (0 means use normal
numbering).  The way the number of a figure or table is printed
is controlled by the contents of the string registers shown
below, with their setting in each case:

	figure_number_form
		normal:		\^Ncurrent_figure	(1, 2, 3, ...)
		per-chapter:	\^Schapter_number.\^Ncurrent_figure
	table_number_form
		normal:		\^N:current_table	(A, B, C, ...)
		per-chapter:	\^Schapter_number.\^N:current_table

When the figures_per_chapter number register is set to 1, the
footnote number will also be reset at the first opportunity in
each chapter.  See node Footnotes for more details.

The standard macro package has a fairly good footnote facility.
Here we describe what it does, and how to use it in the normal
case, and then describe what parts of it you may change, and
how to do it.

The normal way of constructing a footnote when in fill mode is
like this (for instructions about how to do it when in nofill
mode, read on):

	.foot
	...  body of the footnote ...
	.efoot

This text should be placed at exactly the point where you want
the superscript footnote number to appear.  The body of the
footnote will be output at the bottom of the page.  Footnotes
are output before any figures or tables that will appear at the
bottom of the page, and footnotes always come out in order.
The footnotes will be separated from the text by a short
horizontal line, and from the figures below them (if there are
any), by a long horizontal line.  Each footnote will be
preceded by its number, the same number that appeared where you
did the .foot.  If you omit or misspell EFOOT, then R will
throw everything up to the next .efoot (if any) into the
footnote.  Typically the results of this are disastrous, and
result in error message like "macro fn_xxx getting big" and
possibly even "STORAGE FULL".

If you do the above when in nofill mode, you will probably not
get what you want.  Here is the recommended method for doing a
footnote when you are in nofill mode (the footnote itself will
be in fill mode, unless you do a .nf inside its body):

	Here is the first part of the line^Sfn ^G
	.sfoot
	... the footnote
	.efoot
	and here is the rest of the line.

If you really wanted the footnote number at the end of a line,
then omit the space and ^G.  There are other ways that will sort
of work, but all I have tested have one flaw or another.

If the footnote is too large to fit in the space remaining on
the current page, you can do one of two things:

	leave the space blank, and move the current line and the
	footnote to the next page; or

	move the footnote to the next page, but continue with
	text on the current page until it is full.

The choice is controlled by the short_page number register: if
it is 0, then R will fill up the current page; if it is 1, then
the rest of the current page will be blank.  The short_page
register starts set to 1.  R cannot split a footnote into two
pieces.  The primitives available in R make it somewhere
between extremely difficult and impossible to do that, so don't
ask for it - there is no easy fix.

Normally R will start numbering footnotes on each page with 1.
However, the number register reset_per_page controls this
behavior.  If it is set to 1, as it normally is, then the
numbers will start with 1 each time.  But if you set
reset_per_page to 0, then the numbers will increase from page
to page.  The number register figures_per_chapter controls
whether the footnote numbers are reset at the beginning of each
chapter; see node Sectioning for further information.

Special care is exercised in the macro package so that
footnotes within figures (and other kept things) will work
right.  However, do not expect it to work for any but the
simplest situations.

Here are the other things about footnotes that you can adjust (N
means a number register, S means a string register), and their
default values:

	fn - S - ^U\^Ncfn^D  in font fnfont;  This is what is
	output at the .foot.

	fnfont - N - normal_font - the font used to print the
	superscript footnote number at the .foot.

	footnote_font - N - normal_font
	footnote_bold_font - N - bold_font
	footnote_italic_font - N - italic_font
		These control the settings of normal_font,
	italic_font, and bold_font in the footnote body.  The
	font in the footnote body starts set to footnote_font.

	footnote_spacing - S - 1   (.ls ...)  The value for the
	line spacing to be used in the footnote body.

	footnote_starter - S - ^Q \^Ncfn.^Q ^Q    The string
	printed at the beginning of the footnote body.  The
	number register cfn contains the the number of the
	current footnote.

	footnote_sep_width - S - 2.5i  The width of the line
	separating the footnotes from the text (at the bottom of
	the page).

	footnote_space_before - S - 1   The space to output
	(.sp ...) before the footnote separator line.

	footnote_space_after - S - 1  The space to output
	after the footnote separator line.

NOTE:  footnote_space_before and footnote_space_after should be
set before loading the macro package -- they are sampled once
and ignored thereafter.  They are evaluated in the header
environment with the principal font set to heading_font.

Let us say that you wanted your footnote references to be with
special symbols instead of numbers.  For example, suppose that
you wanted to use *, **, ***, etc.  Here is one way you could do
it:
	.sr star1 *
	.sr star2 **
	.sr star3 ***
	... as many as you think are necessary ...
	.sr footnote_starter ^Q \^Sstar\^Ncfn^Q ^Q
	.sr fn ^F\^S_font_\^Nfnfont!!^U\^Sstar\^Ncfn^D^F*

If you had a more complicated set of special symbols, you might
want to use a macro to compute the right one to use:

	.sr fn ^F\^S_font_\^Nfnfont!!^U^Xfnsym(\^Ncfn)^D^F*
	.sr footnote_starter ^Q ^Xfnsym(\^Ncfn)^Q ^Q
	.de fnsym
	.  for count 1 \^A0
	*^G
	.    end for
	.  em

(or any other macro in the place of the little one above).

Hint:  If R complains about undefined number or string registers
in a footnote, you may have done something like this:

	.foot
	...
	.nr foo 5
	...
	...^Nfoo...
	...
	.efoot

The above will not work because the body of a footnote is
always stuffed into a macro.  The problem is that the .NR will
not be executed until the macro is expanded, but interpretation
of the ^N will be attempted while the macro is being defined.
The solution is to put a backslash before the ^N.

The standard macro package provides a reasonably good figure
and table facility.  We will describe the simplest way to use
it, and then explain the different options and how you can set
them up to tailor the facility to your preference.  It should
be noted that the tables we are talking about here are no the
same as what the macro package calls "inline tables" (see node
Setoff Things), or highly structured tables with rows and
columns (see node Columnar Tables for more on them).  It turns
out that the kind of tables we describe here are almost exactly
the same as figures: they are just called tables.  Below we will
use the term figure to mean both tables and figures unless we
explicitly indicate otherwise.

The concept of figure supported by the macro package is bunch
of text, space, etc., of arbitrary size.  The macro package
will keep it on a single page, unless it is bigger than one
page.  Further, figures will be produced in order.  The
additional distinction between figures and other kept things
(see node Keeping) is that figures are automatically numbered
and labelled, and they may have table of contents lines
automatically created.

Special care is used in the macro package to ensure that
figures within kept things will work right.  However, do not
expect it to work for any but the simplest cases.

There are two kinds of figures: normal figures, and page
figures.  Page figures always come out on a separate page, and
always start at the top of the page.  Page figures are more
efficient to produce than normal figures, because they do not
have to be expanded an extra time to discover their size; but
the placing of normal figures in the output is more flexible.

Here is the way to define a figure:

	.begin_figure "the title of the figure"
	...  the body of the figure ...
	.finish_figure

The body of a figure is always made into a macro, so the hint at
the end of node Footnotes applies for figures, too.

If you want a page figure, just substitute .begin_page_figure
for .begin_figure; the .finish_figure remains the same.

Defining tables works exactly the same way, except that the
macro names are different:

	.begin_table,
	.begin_page_table, and
	.finish_table

Output Appearance and Options:

	Figures and tables are always output in order of
definition.  As previously mentioned, page figures are always
output on separate pages.  Normally, regular figures and table
will be output at the bottom of the current page, after any
footnotes, if there is room.  If there is not room, figures and
tables will be output at the top of the next page.  The macro
package will output as many figures, tables, and footnotes as
it can on each page, and (with the exception of page figures)
any "extra" space on a page will be filled with text, if there
is any.
	If you want the macro package to output figures
(tables) where they appear, provided they fit, then you should
set the number register immediate_figure (immediate_table) to
1; it is normally 0.
	Regular figures will be separated from any text or
footnotes above them by a FIGURE SEPARATOR.  A figure separator
will also appear between adjacent figures, and after a figure,
if it might have text under it.  A figure separator consists of
a horizontal line, of width figure_sep_width, preceded by space
of size figure_space_before and followed by space of size
figure_space_after.  These three are all string registers, with
the default values indicated below:

	figure_sep_width - ll-indent!m  (across the whole page)
	figure_space_before - 1
	figure_space_after - 1

NOTE:  figure_space_before and figure_space_after should be set
before loading the standard macro package, because they are
sampled once and ignored thereafter.  They are evaluated in the
header environment with the principal font set to heading_font.

Getting the Current Figure Number:

	The number registers current_figure and current_table
contain the number of the NEXT figure, but this will be just the
per-chapter number if per_chapter is set (see node Sectioning).
The string registers figure_number_form and table_number_form
are better, because they are adjusted when per_chapter is set.
So, you could refer to a figure in the text like this:

	... are shown in Figure ^Sfigure_number_form.
	.begin_figure ...
	...
	.finish_figure

To refer to the figure AFTER it is defined, you should sample
the value of figure_number_form and stick it in a string
register.  For example:

	.sr prog1_figure Figure ^Sfigure_number_form
	.begin_figure "The first program:"
	...
	.finish_figure
	....  See ^Sprog1_figure for details.

The Title Line:

	The form of the title line in a figure (table) is
controlled by a string register, figure_title_form
(table_title_form).  The default value is:

	figure_title_form - \^Sfigure_name_form. \^Sfigure_title
	table_title_form - \^Stable_name_form. \^Stable_title

Both of these actually have a ^F to switch to another font, and
a ^F* to switch back at the end.  The fonts used are controlled
by these number registers, with the indicated default values:

	figure_title_font - bold_font
	table_title_font - bold_font

The string registers figure_title and table_title are always
set to the argument to the begin_xxx macro, that is, the title
that you supplied.

The string registers xxx_name_form have these default values:

	figure_name_form - Fig. \^Sfigure_number_form
	table_name_form - Table \^Stable_number_form

The arrangement of figure_number_form and table_number_form
depends on the setting of per_chapter.  Node Sectioning
explains this in detail.

The title is normally printed at the top of the figure, before
the body.  To have it printed at the bottom, after the body of
the figure, set the number register print_figure_title_top
(print_table_title_top) to 0; it is normally set to 1.  To
suppress printing of a title line completely, set the number
register print_figure_title (print_table_title) to 0; it is
also normally set to 1.

Options in the Body:

	There are several things you can control about the
setting up of the figure body; defaults will be listed below.
First, the string register figtab_spacing controls the initial
setting of the line spacing factor (.ls ...).  The number
registers figure_font and table_font control the initial
setting of the principal and current font.  The string register
figure_before (table_before) is inserted just before the body;
it will always appear on a separate line if it contains
anything.  The string register figure_after (table_after) will
be inserted after the body of the figure (and after the title
line, if it is printed at the bottom of the figure).  Here are
the default values for these registers:

	figtab_spacing - 1
	figure_font - normal_font
	table_font - normal_font
	figure_before, table_before, figure_after, table_after:
		all empty

Each figure always start in nofill mode, with left adjustment (.nf l).

Table of Contents Information:

	For information on this, see node Table of Contents.

The standard macro package has a convenient and highly flexible
facility for producing lists of items, such as this:

		1.  The first item of the list, which exntds
	over two output lines.

		2.  The second, which uses just one line.

		3.  The third, which also uses just one line.

The basic idea is straightforward, but there are a whole raft
of things you can adjust about lists, so we will have to get
more detailed about it.  Also, there is a facility permitting
you to define other things that act like lists, but either set
up the parameters in a particular, unusual way, or need some
special capability not provided.  We defer discussion of this
latter facility until the end of this node.

We will call the different parts of a list, as in the text that
follows 1, 2, and 3, above, ELEMENTS of the list.  There are
two kinds of lists: NORMAL LISTS and INVERTED LISTS.  They are
distinguished by whether the first line of each element is
indented to the right or to the left of the rest of the lines
of that element.  Normal lists indent to the right, as in
typical paragraphs; inverted lists indent to the left.  The
example list above is a normal list, here is an inverted one:

	1.   This is the first line of a list element that
		covers more than one line.  As you can see, the
		first line sticks out to the left.

	2. ...

	3. ...

You may think that the terminology itself is inverted!  (But
that's the way it was done originally, so we will not change
it.)  Additionally, the elements of a list may be produced in
fill mode or nofill mode.  We thus have four different list
macros:

	.list		normal, filled
	.ilist		inverted, filled
	.nofill_list	normal, not filled
	.nofill_ilist	inverted, not filled

To actually use these macros, you proceed as follows:

	.list
	... text for first element ...
	.next
	... text for second element ...
	.next
	.
	.
	.
	.next
	... text for last element ...
	.end_list

All four list macros use the SAME .next and .end_list macros in
this structure.  Now here are the various things you can
control (default values for registers are indicated below).  The
position of the first line of each element, and of succeeding
lines, is controlled by the string registers list_left_margin
and list_indent, as follows:

	normal list
		first line at:	list_left_margin plus list_indent
		others at:	list_left_margin
	inverted list
		first line at:	list_left_margin
		others at:	list_left_margin plus list_indent

These two (list_left_margin and list_indent) are string
registers containing horizontal expressions.  You should know
that list_left_margin is not an absolute position, but rather
the amount by which the indentation is to be increased within a
list.  If you have a list inside a list, the indentation will
be increased twice.  The string register list_right_margin
controls the amount by which the right indentation is increased
in each list, in similar fashion.

The rest of the options are a little bit simpler.  The string
register list_begin_space is the amount to .SP before the first
list element; the string register list_after_space is the
amount to .SP after the last element; and the string register
list_space is the amount to .SP between list elements.  Lastly,
the string register list_spacing is used to set .LS for each
element, and list_keep is the amount to .NE before each
element.

Here are the default values for all of these registers:

	list_left_margin - 800m
	list_right_margin - 800m
	list_indent - 0
	list_begin_space - 1
	list_after_space - 1l
	list_space - 1
	list_spacing - 1
	list_keep - 3

The lists we wrote down in the examples at the beginning of
this node would NOT be produced by the default values.  In
particular, list_indent would have to be set to something like
8 to get an appearance similar to the examples (which were done
by hand).

Some other useful things to know:

	Lists may be used within lists with no difficulties; it
was specifically designed so that this would work and thus
permit lists to be used for making outlines, etc.
	The number register list_count contains the number of
the current element in the current list at all times, going 1,
2, 3, etc.  This can be used to number the elements of a list
automatically, and is particularly effect when used in
combination with the list_start string register.  List_start is
inserted at the beginning of each list element.  It is normally
empty, but if you do the following, you will get automatically
numbered list elements with no effort on your part:

	.sr list_start \^Nlist_count.

(There are two spaces at the end of the above line, so you will
get two spaces between the number and the list element text.
	One other nice feature is that a tab stop is set at the
position list_left_margin plus list_indent, that is, at the
farther right of the places where the first line of each element
starts and the succeeding lines start.  This permits the text
of an inverted list to be all lined up, with a number on the
left, and so forth.  For example, setting list_start to be
list_count followed by a tab (instead of two spaces as above)
will produce output like this when used with inverted lists and
a non-zero list_indent (about 4 or 5 tends to be nice):

	   1.	Here is the first element.  Note how the second
		line comes right under the first.

	   2.	The second element

	Although we did not tell you before, list_indent and
list_space may be set to specific values for a single call of a
list macro by passing the value(s) as arguments to the list
macro.  For example:

	.list 6		- set indent to 6 for this list only
	.ilist 4 2.5	- set indent to 4 and space to 2.5 for
				this list only

Making your own list macros:

	Besides the very flexible list facility presented above,
it is possible to construct your own set of list macros in a
very simple way.  In fact, there are two different things you
can do.  If you want to have something that works exactly like
lists, but sets up the string and number registers a particular
way, you can do this:

	.de foo
	.  begin standard_list	-- use this name
	.    nv list_... ...	-- set up the registers your way
	.    ...		-- use .nv and .sv
	.    _list_ <fill> <invert> <opt-indent> <opt-space>
	.  em

You use it like this:

	.foo
	... first element
	.next
	... second element, etc.
	.next
	...
	.end_list

The name "foo" can be anything you like.  The four things in
brackets should be filled in by you so that you get normal or
inverted lists (0 = normal, 1= inverted), and fill or nofill
lists (0 = nofill, 1 = fill).  The last two arguments,
opt-indent and opt-space, are the same as the optional
arguments to .list, etc., and you can fill them in or not, as
you please.  It may interest you to know that .list, .ilist,
etc., are built just this way, to call _list_ as above.

	The other way to make your own list macros is somewhat
different.  Here you get three new macros, to play the roles of
.list, .next, and .end_list.  The idea is that you can take
advantage of the macro package writer's expertise and
cleverness to do the hard-to-figure-out part.  You supply four
macros defining what to do at the beginning and end of each
item, and the beginning and end of the list as a whole, and then
use a special macro to make up the three ADDITIONAL macros,
which play the role of .list, .next, and .end_list.  The
advantage is that the three macros automatically nest (in the
send that .list can be used inside a list) and the correct
environment switching and initialization is done for you.
Here are the details:

	Step 1.  Define four little macros, having names not
	used before.  We will assume you called them "before",
	"before_each", "after_each", and "after".  The idea is
	that "before" will be called before the first element,
	"before_each" before each element, "after_each" after
	each element, and "after" after the last element.  For
	your information, the entire list is in a begin block,
	and each element (including the invocations of
	before_each and after_each) is in an additional nested
	begin block.  This simplifies writing your macros (see
	node Writing Macros for more information).

	Step 2.  Decide on the name you want for the three
	macros that will take the place of .list, .next, and
	.end_list.  These names MUST be different from any other
	macros, including the ones you defined in step 1.  We
	will assume you called them "first", "middle", and
	"last", for explanatory purposes.

	Step 3.  Invoke def_list_macro:

	.def_list_macro first middle last before before_each after_each after

The def_list_macro invocation will DEFINE three new macros
called "first", "middle", and "last"; those are the macros you
use in the body of your document:

	.first
	... first element ...
	.middle
	...
	.middle
	...
	.last

More Details:

	Any arguments to "first" will be passed through,
unchanged, to "before"; similarly, any arguments to "last" will
be passed through to "after".  Any arguments to "middle" will
be ignored.
	All processing is done in a temporary environment that
is initialized from the environment at the time of the call to
"first".  If you like, you can supply an additional argument to
def_list_macro: the name of an environment to use for
initializing the temporary environment each time.  The
advantage of doing it this way is that many things you may wish
to set (current and principal font, line spacing, tab stops,
etc.) will be done automatically when the temporary environment
is created.  All you need do is setup one environment once at
the beginning, and give that environment's name to
def_list_macro.
	The macros defined (e.g., "first", "middle", and
"last") will nest correctly, just as lists do, and will nest
nicely in other similar structures, too.
	There is an empty macro, called NULL, that you can use
for those macros that you wish to do nothing.  For example, if
everything you want to do in your lists can be set up by just
initializing the environment, then the following will do:

	.ev newenv
	...  set things up ...
	.ev text
	.def_list_macro first middle last null null null null newenv

A similar "roll your own feature" is presented for setoff
things in node Setoff Things.  You may wish to examine that,
too.

Here we describe the table of contents feature of the standard
macro package, including the various options and the format
control available to you.

The macro package accumulates a table of contents through the
document, and prints it at the end, with the correct page
numbers.  For this method (printing at the end) to work, you
are required to tell R where the table of contents is to
appear, and how many pages long it will be.  If you request a
table of contents, it will be produced automatically.

To indicate the placement and size of the table of contents, you
do this at the place you want the table of contents to appear:

	.begin_table_of_contents n

where "n" is the number of pages in the table of contents.  If
you get this number wrong, an error message will be printed
when the table of contents is actually generated.  From the
information it supplies, you can correct "n" and run the
document off again to get a document with correct page numbers.

Options:

	You may control which of chapters, sections,
subsections, etc., appendices, and achapters will have entries
in the table of contents by setting the toc_level number
register.  Here is how it works.  Each kind of sectioning macro
has a level number:

	chapter - 1
	section - 2
	subsection - 3
	subsubsection - 4
	subsubsubsection - 5
	appendix - 1
	achapter - 2

When toc_level is set to "n", then only those kinds of sections
with level numbers less than or equal to "n" will have entries
in the table of contents.  The default setting is 2, which
means that chapters, sections, appendices, and achapters will
all be entered, but none of the others.

You may have lines printed on your terminal as each section is
encountered, indicating page numbers, etc.  To get this, set
the tty_table_of_contents number register to 1 (it is normally
0).

You may have a table of figures and/or table of tables in the
table of contents if you wish.  The number registers
table_of_figures and table_of_tables will cause such tables to
be produced, if they are set to 1.  They are normally set to 0.
No table of figures will be produced if there are no figures;
likewise for tables, so it does not hurt to set the number
registers to 1 even when you have no figures or tables.

R normally assumes that the table of figures and table of
tables, if any, will consume one page, together.  If this is
incorrect, set the number register tof_size to the number of
pages actually needed by the table of figures, and tot_size to
number of pages actually needed by the table of tables.  For
tof_size, round fractions of pages DOWN; for tot_size, round
fractions of pages UP.  This permits R to know on which page
the table of tables actually starts.  Note that the table of
figures and table of tables are considered to be part of the
table of contents for .begin_table_of_contents' purposes, so
the number you supply should be the sum of the number pages
used by the table of contents proper and the number of pages
used by the table of figures and table of tables, if any.

The only other options are whether the include a line for each
of the tables (table of contents, table of figures, and table
of tables) in the table of contents itself.  The number
registers print_toc_toc_entry, print_tof_toc_entry, and
print_tot_toc_entry control each of these separately.  When set
to 1, a line will appear in the table of contents for the
corresponding thing (unless no table of figures (table of
tables) is to be produced, in which case the line for table of
figures (table of tables) is suppressed).  These numbers
registers are all normally 0 (meaning these lines are not
normally produced).

Format Control:

	The detailed format of almost everything in the table
of contents is under your control.  This leads to a whole bunch
of string and number registers, but we will try to sort them
out into easy to understand categories below.

	The FORM registers:

These string registers contain what is actually added to the
table of contents by the different macros (.chapter, .section,
.begin_figure, etc.).  Here they are, with their default values.
To get details on the string registers they use, you may have to
refer to node Sectioning or node Figures.

chapter_toc_form - \^Ssection_number.  \^Ssection_title ^T.^R \^Spage_number
section_toc_form - \^Ssection_number  \^Ssection_title ^T.^R \^Spage_number
subsection_toc_form, subsubsection_toc_form, subsubsubsection_toc_form:
	all just like section_toc_form
appendix_toc_form - \^Ssection_number_title.  \^Ssection_title ^T.^R \^Spage_number
achapter_toc_form - just like chapter_toc_form

figure_toc_form - \^Sfigure_name_form. \^Sfigure_title ^T.^R \\^Spage_number
table_toc_form - \^Stable_name_form. \^Stable_title ^T.^R \\^Spage_number
	Note that the page_number string register insert is quoted twice.
	This is because figures and tables are produced as macros and cause
	another reading of the xxx_toc_form.  The double quotation is needed
	so that the table of contents entry reflects the page on which the
	figure (table) is inserted, rather than where the macro was made. (TAR)

toc_toc_form - Table of Contents ^T.^R \^Ntoc_start_page
tof_toc_form - Table of Figures ^T.^R \^Ntof_start_page
tot_toc_form - Table of Tables ^T.^R \^Ntot_start_page
	Note: the xxx_start_page number registers are set up by
	begin_table_of_contents, automatically.

	The INDENT and FONT registers:

There are a number of string registers that control the
indentation of the various form lines described above, and also
a several number registers describing what font to use for the
lines.  Here is a list of them with their default values:

	chapter_toc_indent - 0
	section_toc_indent - 8
	subsection_toc_indent - 8
	subsubsection_toc_indent - 8
	subsubsubsection_toc_indent - 8
	appendix_toc_indent - 0
	achapter_toc_indent - 0
	figtab_toc_indent - 0

	chapter_toc_font - big_font
	    also used for appendix and achapter
	section_toc_font - normal_font
	    also used for subsection, subsubsection, and subsubsubsection.
	figtab_toc_font - normal_font

	Registers controlling spacing:

There are some string registers that control how much to .SP
before a given kind of table of contents entry, how much to .SP
after it, and how much to .NE before it.  Here they are with
their defaults:

	chapter_toc_space_before - 1
	chapter_toc_space_after - 1
	chapter_toc_need - 5l
	    the above are used for appendix and achapter, too
	section_space_before - 1
	section_space_after - 1
	section_need - 4l
	    the above are used for subsection, subsubsection,
	    and subsubsubsection, too.
	figtab_toc_need - 5l

	The Table of Contents, Table of Figures, and Table of
	Tables announcements:

The beginning of each of these is normally announced with a
header line.  (This is not the same as the entries for these in
the table of contents itself.)  Naturally, the announcement is
inserted only if there is a corresponding table to output.  The
string registers below control the form and spacing of these
announcement lines:

	toc_blurb - ^C^F\^S_font_\^Nbig_font!!CONTENTS^F*
	tof_blurb - ^C^F\^S_font_\^Nbig_font!!FIGURES^F*
	tot_blurb - ^C^F\^S_font_\^Nbig_font!!TABLES^F*
	toc_title - Table of Contents
	tof_title - Table of Figures
	tot_title - Table of Tables
	toc_before_space - 4
	toc_between_space - 2
	tof_before_space - 2
	tof_between_space - 2
	tot_need - 5l
	tot_before_space - 2
	tot_between_space - 2

Some of these need a little more description.  The xxx_blurb
lines are the announcement lines themselves.  The
xxx_before_space registers give the amount to .SP before the
corresponding announcement line.  The xxx_between_space
registers give the amount to .SP after the announcement and
before the corresponding table.  The tot_need register gives
the amount to .NE before the table of tables announcement.  It
is needed because it is the only one of the the three that
might not start at the beginning of a new page.  The title
string registers are used to set the section titles.  The only
effect they might have is on the headings of the pages in the
table of contents, if you set the headings according to the
section title.

The term "keeping" (in this context) is used to mean keeping
some body of text on a single line or a single page.

Line keeping:

	There are several ways you can keep something on one
line.  Often the easiest is to make sure that it has no spaces,
tabs, or absolute horizontal position commands (^P, .hp, etc.;
see node Horizontal Positioning) in it.  Note that the spaces
of concern are R control-spaces, and text spaces are no
problem.  The ".tr @" line of the example set up file in node
Setup gives you a simple way of typing text spaces -- use @.
See nodes Input and Substitution for more details on that kind
of mechanism.
	When building complicated formulae, not only must you
be careful not to use spaces, etc., you must remember to use
relative positioning (.HS) instead of absolute positioning.
The macros described in node Math all work that way.  Another
slightly tricky point: if you write your own macros, don't
forget to put a ^G at the end any text outputting lines.  The
^G will prevent the newline at the end of the line in the macro
from turning into a space in fill mode (or, worse, causing a
line break in nofill mode).
	Your last alternative, which works for anything, is to
use the LKEEP macro.  It works best when used inline:
	^Xlkeep(Here are some words to keep on one line.)
This macro works by using the WIDTH macro (see node Writing
Macros) to find out how big its arguments are (there can be any
number of arguments to LKEEP), and then either sticking them
in, if there is room, or doing a .BJ first if there is not.
See the reference manual for information on .BJ, if you need
it.

Page Keeping:

	The simplest and cheapest way to keep something on a
single page is to use .NE.  The .NE request takes a single
argument, a vertical expression, and if there is not that much
space on the current page, it causes a new page to be started.
Note:  the macro package redefines .NE, so that it will take
into account the space used by any footnotes, figures, etc,
that will be coming out at the bottom of the current page; but
the meaning of .NE is essentially unchanged from the standard
request.
	Another method is to put the text in question into a
figure or table, which are always kept on a single page.  But
that is not always appropriate.  In such cases you may use the
KEEP macro to keep the text on one page.  It works like this:

	.keep
	... stuff to keep on one page ...
	.end_keep

This works by first stuffing the text between the .keep and
.end_keep into a macro, and then finding out how big it is with
the SIZE macro (see node Writing Macros).  Then it does a .NE of
the required amount, and lastly, outputs the actual text.

Sometimes you will have to remember that the body of a keep
becomes a macro first.  The reason is that certain things will
require an extra backslash to make them work right.  For
example:

	.keep
	.nr foo 5
	..... ^Nfoo ...
	.end_keep

will not work, because the .NR will NOT have been done at the
time the ^N will attempt to evaluate number register FOO.  You
will get an error message like "undefined number register".
The solution is to but a backslash in front of the ^N, or to
move the .NR to before the .KEEP.

Another kind of thing that will not work in a .keep is:

	.nr foo foo+1

This will not do what you expect, because the macro is expanded
twice -- once to find its size, and once to produce the output.
Any things like that can be made to work right by making them
conditional:

	.if ~ignore_level
	.  nr foo foo+1
	.  end if

(The ignore_level number register is non-zero when we are
expanding something to determine its size.)

Special care is taken in the macro package to make this work
right when you have a figure or footnote in a kept thing.  It
is done by having the figure and footnote macros do most of
their normal work when we are just finding out the sizes of
things, but the figure and footnote macros suppress the actual
queueing for output.  It is conceivable that there are
complicated situations for which the methods used will not
work.

Node Setoff Things describes some macros that do keeping for
you.  It also describes how to build your own macros that do
so.

If none of the things we have described suits your needs, you
should read up on macros (node Writing Macros), and read
R;KEEP DOC for details on using .keep in your own macros.

By "setoff things", we mean blocks of text that are set off
from the normal flow of text.  Examples of such things are
quotations, program examples, big equations, diagrams, etc.
The figure mechanism provides one form of setoff things, but it
is not appropriate for everything.  In particular, figures will
tend to entered in the table of contents, and have an automatic
naming and numbering scheme, which you may not want to use for
everything.  Of course, tables give you another set of
these names and numbers, but there are still many cases where
you might want "anonymous" set off items.

The list macros, discussed in node List, explain how to get a
list of set off items, and how to tailor the list facility.
However, that mechanism is also inappropriate for items that do
not appear in lists.

To handle these situations, the macro package provides some
macros for you to use, which can be tailored somewhat.  In
addition, it provides a way for you to build more macros that
work in a similar way.  This second facility is nice when you
have several or many items that must all be done in a similar,
and is essential when you have several different types of
things, each of which has many occurrences.  We will describe
the macros that are provided automatically first, and then tell
you how to build your own macros for different kinds of things.

The simplest set of macros provided are .table and .end_table.
The "tables" produced by these are NOT the same as the tables
made by .begin_table and .finish_table.  The coincidence of
names is unfortunate, but historical.  The table macros work
like this:

	.table 3i
	... stuff to set off ...
	.end_table

You can specify any size you like in the .table line; it is used
to do a .NE.  If you leave it blank, 5 is used.  The only
options you can set are three string registers:

	table_begin_space - 1 - amount to .SP before body
	table_end_space - 1l - amount to .SP after bofy
	table_spacing - 1 - setting for .LS in body

There are two other sets of macros provided initially, which
are more flexible than the table macros shown above.  One set
does a .keep of its body, to make sure it stays on a single
page, and the other set does not.  Otherwise they function the
same way.  The keeping form is considerably more expensive, so
we suggest that you use it only when necessary.  See node
Keeping for more discussion on how to keep things on one page.

Here we illustrate how you would use the two sets of macros:

	.example
	...  setoff stuff ...
	.end_example

	.kept_example
	...  setoff stuff, to be kept on one page ...
	.end_kept_example

Note that "example", etc., are the REAL names of these macros!
(That is, we wrote .example because it is actually the name of
the macro, not because we were writing an example.)

That's all there is to it.  There are a number of options you
can control about how the set off text will be produced.  Here
is a list of the registers you can set, their default values,
and their effects.  The number registers are presented first,
and then the string registers:

	example_font - normal_font - sets the principal and current font
	example_fill - 0 - fill nor nofill? (1 = fill)
	example_adjust - 0 - adjustment mode (0 = left, 3 = both)
	example_tabs - 16 - number of tab stops to set

	example_left_margin  - 500m - amount to increase indent
	example_right_margin - 500m - amount to increase rindent
	example_spacing - 1 - .ls ...
	example_begin_space - 1l - amount to .sp before body
	example_end_space - 1l - amount to .sp after body
	example_tab_width - 8 - distance between tab stops

All other things are initialized from the current environment.
The body itself is produced in a temporary environment, and is
always inside a begin block.  Of course, in a kept_example, the
body will be stored in a macro, its size determined, and then
it will be output, as in .keep.  See node Keeping for details
on problems you might run into because of that.

The tab stops are set starting at the indentation, so if you
have example_font set to select a fixed width font, things will
line up the way they do on the screen in your editor.

Examples of either kind may be nested in the other, with no
problems, EXCEPT: don't put a kept_example inside a
kept_example.  There is no need to do so, anyway.

Making your own setoff macros:

	There are two kinds of things you can do in terms of
making macros tailored to what you want to do:

	1 - Have a macro set up the example options, and then
	use the table or example macros essentially unchanged, or

	2 - Construct an analogous set of macros where you set
	up things yourself.

In the first case, you write macros according to these
skeletons:

	.de new_table		-- or any other NEW macro name
	.  begin standard_table
	.    nv ....		-- use .NV and .SV to set options
	.    table1 \^A0	-- pass <size> argument through
	.  em

	Used as:
		.new_table <size>
		... body ...
		.end_table		-- same as before

	.de new_example		-- analogous to new_table
	.  begin standard_example
	.    nv ...
	.    example1
	.  em

	Used as:
		.new_example
		... body ...
		.end_example

	.de new_kept_example		-- analogous to new_table
	.  begin standard_example
	.    nv ...
	.    kept_example1
	.  em

	Used as:
		.new_kept_example
		... body ...
		.end_kept_example

Note: .table and .end_table, .example and .end_example, and
.kept_example and .end_kept_example are defined in terms of
table1, end_table1, example1, end_example1, kept_example1,
and end_kept_example1 just to make it easy for you to do what is
shown above.

If the above method do not meet your needs, perhaps method 2
will.  In this second method, you write two macros: one to set
up and do what needs to be done before the body of the things
you are defining, and one to be done after.  Then you use a
special macro to create two NEW macros, which call upon your
macros, but have these additional features:

	They nest properly;
	They switch environments correctly;
	They set up an extra begin block for you.

Here are the details:

	Step 1 - Define two little macros, one to be invoked
	before the setoff stuff, to set things up, and one to do
	anything needed at the end.  We will assume for the sake
	of argument that you called them "before" and "after".

	Step 2 - Pick two previously unused names.  If they are
	"first" and "last", then they "fill in the blanks" in
	this way when you use them:

		.first
		... setoff stuff ...
		.last

	Step 3 - Use .def_setoff_macro to actually construct the
	macros "first" and "last" in terms of "before" and
	"after", like this:

		.def_setoff_macro first last before after

If you want either of the "before" or "after" macros to do
nothing, you can use the NULL macro, which does nothing.  For
example:

	.def_setoff_macro foo bar setup null

There is also a macro called .def_kept_setoff_macro that works
in exactly the same way as .det_setoff_macro, except that it
does a .keep of the body of the setoff stuff.  It may interest
you to know that the table and example macros are actually
constructed this way with def_setoff_macro and
def_kept_setoff_macro.

More details you should know:

	The macros constructed by def_setoff_macro and
def_kept_setoff_macro will call your "before" and "after"
macros in a temporary environment in a begin block.  The body
of any particular use will be expanded in this same environment
and begin block.  Any arguments given to "first" will be passed
directly to "before", and any arguments to "last" will be
passed to "after".  That is how itable gets the size of the
table in a .table, for example.  In a kept setoff macro, the
"before" and "after" macros are invoked inside the .keep,
inside an extra begin block, if this makes any difference to
you.
	The temporary environment created by your "first" macro
is normally initialized from the environment current at the
time "first" is invoked, but if you give def_setoff_macro or
def_kept_setoff_macro one more argument, it will use it as the
name of an environment, and initialize the temporary
environment from that environment.  If everything of interest
to you can be expressed in an environment, then this provides a
very simple and efficient way to tailor a macro.  For example,
say that you have set up the "foo" environment to be what you
need.  Then the following will create two macros that "do the
right thing":

	.def_setoff_macro first last null null foo

There are a number of little macros in the standard macro
package for assisting you in writing mathematical formulae,
equations, and the like.  They have been made up to work well
together, and you should read node Writing Macros before
attempting to write your own macros for this sort of thing.

These macros are setup so that if you place surrounding things
directly adjacent on both sides (no control-spaces, that is),
then whole formulae will move as a unit.

Features provided:

	Some of these features have been described elsewhere,
but we will give you a complete list, anyway:

	superscripting and subscripting -- Simple situations are
		handled as described in node Superscripting and
		Subscripting, but some of the more common
		complicated cases are described below.

	aligning items -- Node Alignment has a complete
		discussion; see also node Columnar Tables.

The rest of the list is a macro by macro description:

				arg1
^Xdiv(arg1 arg2) generates:	----
				arg2

	Notes:  Works for any arguments, including other invocations
	of div.  The line will be as long as the longer of the
	two arguments.

			     ___
^Xsqroot(arg) generates:   \/arg

	Notes:  The string register SQROOT can be set to a nice
	square root symbol in some font, if you like; it starts
	set to a backslash followed by a slash, as above.  The
	line at the top is drawn from the beginning to the end
	of arg, one line up.  The string register SQVOFF can be
	set to change the vertical position of the line; it is
	the distance from the baseline of "arg" to the position
	where you want the line.  It is normally set to
	"fheight!m".  The string register SQHOFF can be set to
	the amount by which you want the line to extend to the
	left beyond "arg".  It may be positive or negative; it
	starts at 0.  The idea is to set it so that the line
	just joins up with your chosen square root sign.

	Only one size of square root is supported, but you could
	easily write a macro that sets the SQROOT, SQHOFF, and
	SQVOFF string registers for a variety of different
	square root symbols, and get different sizes that way.
	You may have to put ^V adjustments into the string
	register SQROOT to get a pleasing appearance (see node
	Supscripting and Subscripting).

					item1
^Xabove(item1 item2) - generates:	item2
	That is, item1 centered above item2; item2 on the
	baseline.  The string register ABOVE_SEP controls the
	amount of white space between item1 and item2; it is a
	vertical expression, normally "20m".

^Xbelow(item1 item2) - generates:	item2
					item1
	That is, item1 centered below item2; item2 on the
	baseline.  The string register BELOW_SEP controls the
	amount of white space between the two; it is a vertical
	expression, normally "20m".

						item3
^Xbottop(item1 item2 item3) - generates:	item1
						item2
	That is, item1 with item2 centered below it, and item3
	centered above it.  This is goos for summations, unions,
	etc.  For example,  ^Xbottop(U n=1 |a|)^b^Xsub(n)
	becomes:	|a|
			 U a
			n=1 n
	The string registers BOTTOP_TOP_SEP and BOTTOP_BOT_SEP
	control the amount amount of white space between item1
	and item3 and item2 (respectively).  They are normally
	both set to "20m".

					item2
^Xsubsup(item1 item2) generates:
					item1

	(But closer together vertically.)  This can be used to
	give something both superscripts and subscripts
	simultaneously.  For example, a^Xsubsup(j i) produces
	this:	 i
		a
		 j
	The top and bottom items are normally done with a single
	^U or ^D.  If your formulae overlap when output that
	way, you should include extra vertical adjustment in the
	items themselves, e.g.:  a^Xsubsup(^Di^Xsup(j)^U ^Um^Xsub(n)^D)
	to produce this:	 m
				  n
				a
				  j
				 i
	and so forth.

Well, that's it.  But with care, you should be able to build
similar macros or special cases readily; and the above handle a
lot of things anyway.  Node Writing Macros gives some hints on
writing your own macros for this kind of thing.

There is not too much we can do here except describe some
general principals, and point you to available macro packages.

R can do pretty good horizontal positioning, and draw horizontal
lines, but its notion of the page is a bit primitive, and it
would be non-trivial to try to draw vertical lines.  So don't
expect to be able to draw boxes around stuff, etc., very easily.

It is not too hard to get straight columns, even with optional
centering and right flushing of items in columns (using ^C and
^R), but you get multiple columns of FILLED text  very easily
(it requires writing macros to do the justification - ugh!).

If you want the width of a column determined by the widest
element in it, then the text will have to be scanned three
times, at least: once to put it in a macro, a second time to
find the sizes, and a third time to actually output it.  The
WIDTH and SIZE macros do just that kind of thing.  They are
described in more detail in node Writing Macros.

You can get a simple columnar table in this fashion:

	1.1^P(pos2)1.2^P(pos3)...^P(posK-1)1.K
	2.1^P(pos2)2.2^P(pos3)...^P(posK-1)2.K
	...
	N.1^P(pos2)N.2^P(pos3)...^P(posK-1)N.K

Naturally, you can change indent to adjust the position of the
first column, or even precede it with ^P's.  You can use ^C or
^R before an item to center or right flush it in its column,
etc.  All the column macro packages generate output like this
when done, but they may do a lot of work first to figure out
the ^P positions, and possibly rearrange the items from the way
you supplied them.

A technique even easier than the above is to use a fixed width
font, and line things uyp in your text editor.  Of course, it is
not as flexible, and fixed width fonts don't look as good,
typically.  You can also try it with variable width fonts, but
you will probably have to adjust it some to get the desired
appearance.

The package in R;TAB RMAC is simple to use, and may save you a
lot of trouble over the above, by-hand methods.  It has good
instructions at the beginning of the file.  The package in
R;COLUMN RMAC can do more than the TAB package, and is only
slightly harder to use.  It also has instructions at the
beginning.  If you plan to do any amount of tabular work, you
should read up on these -- they can save you a lot of grief.

There are several packages available for assisting you with
constructing bibliographies and references.  They are:
	R;REF RMAC
	R;REF1 RMAC
	R;REF2 RMAC
	R;REF3 RMAC
The general method of use for each is the same:

1. At the beginning of your file, you define the references, in
the order in which you wish them to appear in the bibliography.
(The bibliography itself will be remembered and produced later.)
Each reference is defined this way:

	.ref Foo67
	Foobar, John,  Hacking at M.I.T., April, 1967.
	.em

2.  To refer to any of these in the text, you insert the string
register of the name given in the .ref line:

	... and so was Foobar's work [^SFoo67].  ...

3.  At the place where you want the bibliography to appear, do
this:
	.insert_refs

If you need something different, just take one of these
packages (they are all very much the same), and make a private
copy, modified as you see fit.  You should be able to inspect
them and see what they do fairly readily by now.

Here are the details on the four packages provided:

	In each, the number registers ref_margin and ref_indent
are used to set up the margins when the bibliography is output.
The INDENT is set to the sum of ref_margin and ref_indent, and
the RINDENT is set to ref_margin.  The first line of each
reference will begin at ref_margin, and hence will stick out to
the left of succeeding lines for the same reference.  The bodies
of the references, as opposed to the reference numbers or codes,
will always start at ref_margin plus ref_indent.  The
bibliography is produced in fill mode, with the principal and
current fonts both 0.  There is a ".ne 3l" before each
reference.

Note: The beauty of these files is that you can change the
format used by just changing which file you .SO, because they
all use exactly the same initial set up (.ref) the same
referencing scheme (the string registers) and the same
inserting technique (.insert_refs).  If there were sufficient
call for some other flavor, it could easily be added.

	REF - The references are numbered, in the order you
originally gave them.  So, ^SFoo67 might turn out to be "8", or
something.  The bibliography lines start with the reference
number followed by a period, e.g., "1.".  The default values
for ref_margin and ref_indent are both 500 (i.e., 500 mils).

	REF1 - The references come out as the keyword string
you used in the .ref line; e.g., ^SFoo67 will print as "Foo67".
The bibliography line would start with "[Foo67]".  The defaults
for ref_margin and ref_indent are 500 and 1000, respectively.
(The 100 is to leave room for the [Foo67].)

	REF2 - CACM format:  The references should be entered
in alphabetical order.  When referred to in the text, the
reference will print as number.  The bibliography lines use the
same number, followed by a period, both in boldface (according
to the setting of bold_font when the REF2 package is read).
That is followed only by a space before the rest of the line
appears.  When you do .insert_refs, it will output a header
line, "References", in boldface, followed by the references.
The ref_indent number register is ignored; ref_margin is
normally 500.  Single spacing is used.

	REF3 - This differs from REF2 only slightly.  The
"References" line will be centered, and there will be one blank
line before each reference.

There are many topics that could be covered here; we will not
attempt to make you expert in anything, but try to give you
some hints and references.  First, there are some mechanisms of
R that you should understand before attempting write anything
except simple macros.  We will introduce you to the subjects
listed below, and give you some hints.  Beyond that, you should
read the reference manual, and perhaps look at the macro
package itself, to get ideas of more sophisticated techniques
and tricks.

Defining a macro is quite simple (although getting it RIGHT is
another matter!)  You just use the .DE request:

	.de <macro-name>
	... body of macro ...
	.  em

The macro definition continues until the first line with .EM.
If, for some reason, you need a line with .EM on it in the macro
itself, you must write it this way:

	.de <macro-name>
	...
	\.   em
	...
	.  em

The \ PROTECTS the "." (which is actually a control-.) from
being interpreted until later.  The .DE request is actually a
little more flexible:

	.de <macro-name> <term>

defines a macro that is terminated with ".<term>" instead of
".EM".  Further, after the macro is defined, the .<term> line
will be executed as a normal request line, so you may have to
define a little macro named <term>, which does nothing:

	.de <term>
	.  em

You may in fact define permit a macro to be terminated by one of
a set of terminators:

	.de <macro-name> <term1> <term2> ... <termN>

This would be useful in a kept form of the LIST macros, where
aech item is accumulated into the body of a macro, but the
terminator may be "next" or "end_list", and you cannot tell in
advance which it will be.  Thus, .list and .next could have in
them a .DE line like this:

	.de foo next end_list

It is considered good style to indent everything in the body of
macro that you can, by a space or two, to make it more
readable.  (See also node Variables and the Stack for more
suggestions on this.)

The .KEEP and .END_KEEP macros (see node Keeping) use the
optional terminator feature, something like this:

	.de keep
	...
	.  de keep_holder end_keep
	.  em

	.de end_keep
	...
	.  em

That is, when .KEEP is run, it will cause the definition of a
new macro, KEEP_HOLDER, which will hold your kept stuff, up
through the next .END_KEEP.  The .END_KEEP is also invoked,
which has the effect of doing an appropriate .NE, and then
invoking the recently defined KEEP_HOLDER to actually produce
your kept item.  (The actual macros are more complicated, to
take care of other problems, but this is the essence of the
scheme used.)

When a macro is DEFINED with .DE, nothing in its body is
"evaluated", EXCEPT any unprotected ^N's, ^S's, or ^A's.  These
are evaluated so that the mechanism will be powerful enough
that you can write macros that define macros, etc.  If you are
NOT defining a macro in a macro, then the general rule is that
every ^N, ^S, and ^A should have one backslash in front of it
to protect it.  That way it will not be evaluated when the
macro is defined, but rather when the macro is invoked.  If you
define a macro in a macro, then most of the ^N's, ^S's and ^A's
will need TWO backslashes, etc.  The macro .def_setoff_macro is
good example of this sort of thing.

Control-A:

The R control character, control-A, is the method by which
macros gain access to their arguments.  (Node Macro Invocation
describes how the argument are defined for each invocation;
perhaps you should review it if you do not feel comfortable
with the subject.)  The arguments are referred to by position,
the first one begin numbered 0, the second argument 1, etc.  To
get argument N, you write ^AN (or, more likely, \^AN).
Actually, that works only if N is between 0 and 9.  ^A(exp) can
be used for an arbitrary expression, including ones bigger than
9.  The number register NARGS contains the number of arguments
supplied to the current macro.  For example:

	.  for n 0 nargs-1
	.    ... \^A(n) ...
	.    end for

Macros can even distinguish whether they are called with a
control-. or control-', with "^A.", which yields "1" if the
macro was called with control-., and "0" otherwise.  "0" is
also the result if the macro was called with ^X.

	One way of thinking of macros is as if they are like
string registers.  In fact, they work almost exactly the same
way.  Of course they are defined differently, and different
things trigger their insertion, but both are essentially a text
substitution mechanism.  What that means is, that the insertion
of a string register, or invocation of a macro, are little more
than just the substitution of the contents of the string
register (the body of the macro) in the place of the call, in
the input stream.  That is in fact how they are implemented.
So, although macros are like programs, there are ways in which
they are NOT like programs, too.
	For example, besides grouping together requests in
order to perform a specific function, macros are also used to
hold text to be printed later.  That is how table of contents,
references, keeping, etc., are implemented.  For these things,
it is often convenient to add a little bit to the macro each
time; the .AM request does that.  It is also possible to access
a macro body as a string.  See the reference manual for details
on these features, and also for information on the string
processing available.

	In R, certain properties controlling the appearance of the
output are part of an ENVIRONMENT.  The interesting thing about
this is that if you change to another environment, all those
properties change, "magically" and instantaneously.
	Environments have names, and the name of the current
environment is always available in the string register ENV.  In
fact, on way to change to other environments is to change ENV.
The other relevant requests are:

	.EV e - Change to environment "e".  If it does not
	exist, then create it, initialized in a standard way.

	.ES e - Save all parameters of the current environment,
	INCLUDING ANY PARTIAL OUTPUT LINE, in environment "e".
	A new environment is created if "e" does not exist.

	.XE e - Expunge (throw away) environment "e".  If "e" is
	the current environment, it will not be thrown away
	until another environment is selected.

	The initial environment is called TEXT.  Some other
environments used in the macro package are CONTENTS (table of
contents), TABLES (figures and tables), FOOTNOTES (footnotes),
HEADER (headers and footers), IGNORExxx (in IGNORE), LISTENVxxx
(in lists), and SETOFFENVxxx (in setoff things).  In general,
things are done in other environments to prevent irrevocable
side-effects, such as a line break that would force out a
partial line in the wrong place.

Here is a list of the things that are kept with each
environment:

	the partial output line
	principal and current font, and a font stack for ^F and .FS
		(FONT, PFONT)
	line spacing (LS)
	fill and adjust modes (FILL, ADJUST, ADJUST_FILL, ADJUST_NOFILL)
	vertical offset (VOFF)
	indentation (INDENT, RINDENT, and temporary indent)
	tab stops (.TA, etc.)
	underscoring (UL, UL_SPACE, and UOFF)

Everything else is common to everything is R, so care must be
used to change such things back if you want to change a value
temporarily.  See node Variables and the Stack for some hints
about that.

To make saving and restoration of values easier, and reduce
problems arising from unwittingly using the same register name
in two or more places, R provides what we call a STACK of
values for string and number registers.  This stack work in
conjunction with the flow control requests, .BE, .IF, .EF, .WH,
and .FR.  We will explain the meaning of the control structures
in a moment.  For now, all you need to know is that we will
call the lines read between a .BE, .IF, .EF, .WH, or .FR and
the next .EN a BLOCK, and say that we are in a BLOCK during the
time those lines are read.

When you are in a block, the .NV and .SV requests may be used to
save the previous value of a number or string register, and set
the register to a new value.  The register need not have a
previous value.  Here is an example:

	.be bar
	.  nv foo 10
	....
	.  en

The nice thing about this is that when the .EN comes by, all
the .NV's and .SV's done since the .BE will be undone.  In this
way we can use FOO in the block above temporarily without
caring whether FOO was being used somewhere else.  This feature
is convenient a lot of the time, but becomes essential when
writing macros such as .LIST, which can be nested inside
themselves.

Stylistic note:

	The macro package is set up so that the following long
names are equivalent to the short names given in the R manual.
It is considered good style to use the long names, and we will
do so from now on:

	.begin		.be
	.else		.ef	-- use the appropriate one of these two
	.elseif		.ef	--
	.for		.fr
	.while		.wh
	.end		.en
	.lbegin		.if	-- when used just to introduce a new block

It is also customary to put the name of the kind of thing ended
after .END, e.g.:

	.for n 1 nargs
	...
	.  end for

Further, it is good style to indent one or two spaces for each
level of blocks you are in.  For example:

	.de foo
	.  lbegin
	.    nv foo 0
	.    for n 1 nargs
	.      nr foo foo+n
	.      end for
	.    end lbegin
	.  em

[The above is a useless macro!]

In addition to .NV and .SV, there are two requests, .HV and .VV
that make it easier to do calculations in blocks.  .HV and .VV
work exactly like .HX and .VX, except that they save the number
register that they will be changing.  The saving is done after
the new value is computed, but before it is stored, which is
true of .NV and .SV, too, so the following works:

	.hv indent indent!m 1i

An obscurity:

	In some cases care must be used about the order in
which things are saved and restored, but it usually does not
make too much difference.  Here is a case where it does:

	.nv fill 0
	.nv adjust 0

The problem here comes if someone change FILL later.  Say a .FI
is done.  Then when the .END is encountered, ADJUST will be
restored.  BUT, it will be the fill mode adjust that is
restored, not the nofill mode adjust.  Therefore, when you wish
to save and restore FILL and ADJUST safely, you can either do
this:

	.nv fill 0
	.nv adjust_nofill 0

(or similarly for fill mode), or this, which works when you do
not know in advance what the new fill mode will be:

	.nv fill \^A0
	.nv adjust 0
	.nv fill \^A0

This works because FILL is restored before ADJUST, so that the
correct adjust mode is restored.  If you thought of just
swapping the order of saving fill and adjust, that won't work
because then the wrong adjust mode may be set up, etc.

It is possible that you might run into other situations like
the one shown above, but we believe not.

Control Structure:

	The reference manual discusses this in detail, but here
are a few tips:

	.FOR and .WHILE can be used only in macros (because they
	involve going backwards, so the text must be handy)

	Only .BEGIN can be put in a macro without a matching
	.END in the same macro.  The LIST, EXAMPLE, KEEP, and
	other macros provide examples of its use.

	.LBEGIN is a convenient way to start a new block for
	saving and restoring some registers.

	Sometimes you have to introduce a variable before you
	have a value for it, so that it will not be lost.  For
	example:
		.if ...
		.  nv foo exp1
		.else
		.  nv foo exp2
		.  end if

	will not work.  You should do this instead:

		.nv foo 0
		.if ...
		.  nr foo exp1
		.else
		.  nr foo exp2
		.  endif

One last hint:  Don't forget that every time around a loop
(.FOR or .WHILE), and every macro invocation involves scanning
a potentially large amount of text, and R's speed in limited by
its character processing rate.

Below is a list of little hints, in no particular order, that
may help you in writing your own macros.

Finding sizes of things:

	The macro package provides two very useful macros for
this, .SIZE and .WIDTH.  They work like this:

	.width arg - Finds out the width of "arg", and saves it
	in the number register WIDTH (in mils).  It also saves
	its height above the baseline in the number register HA,
	and its height below the baseline in HB.

	.size name - Finds of the vertical size of the macro
	"name", when expanded.  The number register SIZE will
	contain the size in mils.

Both macros work by expanding their arguments in a temporary
environment set up specially so as to cause no side-effects.
The macro .IGNORE provides that environment.  If you feel the
need to write other size finding macros, make sure you
understand the operation of WIDTH and SIZE, first; read the
macro package!  If you are not very careful you can cause weird
things to happen to your output.

Gluing:

	When writing macros that output little pieces of text,
don't forget that usually you want to follow each text line in
the macro with a ^G, so that the newline will not be output as
a space, or cause a line break.  Note that you can put ^G's at
the start of a line, to eat the PREVIOUS newline, provided
there has not been a breaking request in between.  However,
macros that are invoked inline have an implicit ^G both before
an after them.  So, generally a ^G is necessary only at the end
of each text line in a macro.

Mathematical Macros:

	The crucial things to remember are:

	Don't forget ^G's.
	Use the variable stack, so your expressions will nest.
	Use .WIDTH to find widths and heights of
	    expressions; in particular, this kind of
	    construction will not work in every case:
		.nr temp hpos
		... output something ...
		.hs temp-hpos!m
	    It fails because the outputting might force a line
	    break, which makes the second measurement of hpos
	    bogus compared to the first one.
	Use .HS, never ^P, .HP, or setting HPOS.
	Use relative adjustments to VOFF (^U, ^D, ^V(+...),
	    ^V(-...)).
	When drawing a line with underscores, be careful that
	    the states of UL, UL_SPACE, and UOFF will be
	    restored correctly.  For example:
		.lbegin
		.  nv ul 1
		.  nv ul_space 1
		.  nv uoff voff
		.  hs ...
		.  end lbegin

Passing Arguments:

	If you wish to pass the arguments of one macro through
to another macro, you can use the following lines:

	.  sr args \^A:0
	.  for n 1 nargs-1
	.    sr args \^S:args \^A:(n)
	.    end for
	.  foo \^S:args

The ":"'s are required if you want to make sure that control
characters in the arguments are not interpreted too soon.
Naturally this works with any number of arguments.  A slight
variation will "glue" all the arguments together into one
argument, with spaces in between:

	...
	.  foo {\^S:args}

There are other useful variations on this trick.

This node is organized as a collection of minor hints and
techniques, in no particular order.

Debug and friends:

	R supports a number register called DEBUG, which is
normally 0, but is set to 1 if you put a -D in the command line
(see node Invoking R for details on the command line).  There
is no other way to set DEBUG.  DEBUG is tested at various
places int he macro package, and if it is set, additional
information will be printed on your terminal (or in your error
message file).  In addition, there are number registers called
HEADER_DEBUG, FOOTER_DEBUG, FIGURE_DEBUG, and FOOTNOTE_DEBUG,
which give extra information concerning the feature they name.
They are normally off (0); setting them to 1 turns them on.
They maybe turned on and off at your whim.
	This information can be very helpful is figuring out
problems such mysterious blank pages near a figure or footnote,
etc.  [Note: a common cause of that kind of misbehavior is
something that changes size between the time its size is
measured and it is actually printed.  Naturally figures,
footnotes, etc., are not SUPPOSED to change size, but sometimes
they do, if you put "funny" stuff in them.]

Tracing:

	R has a very useful trace feature, controlled by the
TRACE number register.  Normally it is 0 (off); setting it to 1
turns tracing on.  Another way to turn tracing on is to put -T
in the command line (see node Invoking R), but it is often more
useful to turn tracing on just in the region of the problem.
For example:

	.nr trace 1
	...
	.nr trace 0

You can turn tracing on and off as much as you like.
	What you get when tracing is on is two extra files
describing what R actually saw.  If the first name of your input
file is FOO, they will be called FOO RTA and FOO RTB (for R
Trace A and R Trace B).  The A file shows every character
scanned.  For example, if you have written:

	.sr foo ^Sralph!or

then the A file will show both scanning of the string register
name "ralph", and the characters that come out of it, etc.
	The B file is a "higher level" trace, often easier to
wade through to find the problem.  The B trace shows only the
actual values seen by each request.  For example, in a .nr, all
it will show is ".NR FOO 1045" where 1045 was the value of what
might have been a quite involved expression.  Other things are
made briefer and standardized in similar ways.
	Tracing can be very useful, but the output can be HUGE,
because of all the extra stuff that happens behind your back in
the macro package.  That is why we suggest you be selective in
the region that you trace.
	About the only thing tracing cannot do is show you what
you output looks like.  For debugging a document, you can often
figure things out by examining in your text editor output for
the LPT device.  But sometimes the problem only shows up on a
particular device, and then you must apply your deductive
powers.

Some Common Mistakes:

	Forgetting a ^F* to switch fonts back.

	Forgetting a matching .END, .FINISH_FIGURE, .EFOOT,
	.END_LIST, etc.  Some of these will cause R to attempt
	to put large parts of your file into a macro, and say
	"macro getting big", or even STORAGE OVERFLOW.  (On the
	larger computers, these mistakes are the main causes of
	STORAGE OVERFLOW.)

	Causing a line break by forgetting a ^G, or inserting a
	space or newline in the inappropriate place.

	Not getting a line break, because you are not in nofill
	mode, or you omitted a space somewhere.

	Omitting a backslash where you need it.  This often
	results in an "undefined register" message.

Here are some of the things that we did not discuss.  You are on
your own (see the reference manual, etc.)

	Indexing, .II, .ID.
	Traps, .ST, .CT, .RT
	Writing to files, .WF, .WS, .WM, .WL, .WA, .WE
	Terminal I/O, .RL, .TM
	Miscellaneous Requests: .PN, .BJ, .ND, .SD, .XN, .XS,
		.SB, .SI, .SC, .SL, .RM, .EQ, .MS, .NX, .RD,
		.EX, .XC, .PR, .PW, .PL
	Other control characters: ^K
	Other built-in registers: DAY, ENABLED, END_OF_SENTENCE,
		EVEN, FHEIGHT, FWIDTH, HABOVE, HBELOW,
		INTERACTIVE, LPI, LVPU, MACRO_ARG_LIMIT,
		MACRO_LIMIT, MARGIN_LIMIT, MAXHPOS, MONTH,
		PAGE_EMPTY, PBOTTOM, PL, PLEFT, PRIGHT,
		PRINTING, PTOP, RUNTIME, SPACING, STATS,
		VERSION, VPLOST, VTRAP, YEAR, CFDATE, CFILENAME,
		CFTIME, DATE, DEVICE, FDATE, FILENAME, FTIME,
		LINENO, MACRO, SDATE, TIME, USER

Not to mention many things internal to the macro package.