Trailing-Edge
-
PDP-10 Archives
-
mit_emacs_170_teco_1220
-
info/rguide.info
There are no other files named rguide.info in the archive.
This is the file containing the INFO-ized documentation on using R with
its standard macro package.
File: RGUIDE, Node: Top, Up: (DIR), Next: Generalities
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.
* Menu:
* Generalities:: This node contains such information as where to
find documentation, conventions used in this
file, the place of R in the document preparation
process, etc. Also, how to report bugs, how to
get on the mailing list, etc.
* Setup:: How to set up the beginning of your file to use
the standard macro package.
* Input:: How R scans a file. In particular, how to get
'funny' characters to work right, etc.
* Registers:: How string and number registers work. This
knowledge is necessary for you to get anything
other than the default actions of the macro
package.
* Expressions:: How to write down numerical expressions,
including more complicated horizontal and
vertical measurements, such as "twice the
current indentation", etc.
* Backslash:: The various roles of \ in R.
* Justification:: A review of how filling and adjusting work in R.
The role of the space character.
* Fonts:: The various facilities for switching fonts are
described here.
* Macro Invocation:: How to call macros. This describes how to deal
with getting special characters into macro
arguments, etc.
* Page Layout:: How the standard macro package lays out the page
into vertical sections (top margin, text area,
bottom margin, etc.)
* Line Spacing:: How R determines the distance between lines, and
how you can control it.
* Line Layout:: How R lays out each output line, and macro
package facilities for setting line margins.
* Horizontal Positioning::
How to control fine positioning of items on the
output line.
* Text Features:: This discusses a raft of little, useful things,
such as super- and subscripting, underscoring,
overstriking, output translation, and
hyphenation.
* Alignment:: How to get things on different lines to line up
vertically in various ways.
* Sectioning:: The macros available for organizing a document
into chapters, sections, appendices, etc.
* Footnotes:: How to use the footnote facility.
* Figures:: How to use the figure and table facility.
* Lists:: The facility for lists of things, e.g.:
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.
* Table of contents:: How to get a table of contents, and how to
control its appearance.
* Keeping:: How to keep things on a single line or a single
page.
* Setoff Things:: Here we describe the facilities available for
setting things off in the text. Examples of
this kind of thing are quotations, equations,
program text, and various kinds of pictures and
tables.
* Math:: Here we describe the facilities available for
doing mathematical equations and formulae, and
give some hints on how to go beyond what is
standardly available.
* Columnar tables:: Introduction to methods of making tables that
consist of vertical columns that must be aligned
in a particular way.
* References:: Introduction to the packages available for
producing bibliographies and keyed references in
running text.
* Writing Macros:: Conventions and hints on macro writing in
general. Specific hints are given in other
places.
* Debugging:: Some hints on how to debug problems encountered.
File: RGUIDE, Node: Generalities, Up: Top, Previous: Top, Next: Setup
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.
* Menu:
* What R does:: R's place in the document preparation process.
* Documentation:: What is available and where to find it. How to
report bugs. How to get on the mailing list.
* Filenames:: Things you should know about how R deals with
filenames.
* Output Devices:: Things you should know about using the various
output devices available with R.
* Invoking R:: How to run R.
File: RGUIDE, Node: What R does, Up: Generalities, Next: Documentation
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
XGP XGP XGPSEND
LPT TPL EXEC PRINT command, FIFTH
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.
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. Maintained randomly; no Dover
capability.
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. Maintained randomly. No Dover capability.
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).
File: RGUIDE, Node: Documentation, Up: Generalities, Previous: What R does, Next: Filenames
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 available, written by Judi Jones. If you have
never used R, and especially if you have never used any formatter, read
the Primer first -- it will really help you get started. The Primer is
AI Memo No. 585, available from the AI document people. The Primer
complements this guide, 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 of the guide 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. There used to
be a file R;RMACO INFO for documenting the macro package, but that file
is OBSOLETE. This file is INFO;RGUIDE INFO. (The corresponding names
are used on XX and other TOPS-20's.)
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.
File: RGUIDE, Node: Filenames, Up: Generalities, Previous: Documentation, Next: Output Devices
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 OR
/device/directory/name1.name
In the .so command of R, you may
omit device: (/device/) if it is DSK: (/dsk/)
omit directory; (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: (/device/) if it is DSK: (/dsk/)
omit directory; (/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 is to use the "/" form of file-names, illustrated
above.
On TOPS-20:
Full filenames on TOPS20 have the form:
device:<dir1.dir2.---.dirN>name1.name2.version OR
/device/dir1/dir2/---/dirN/name1.name2.version
In the .so command of R, you may
omit device: (/device/) if it is DSK: (/dsk/)
omit <dir1.dir2.---.dirN> (dir1/dir2/---/dirn/) 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: (/device/) if it is DSK: (/dsk/)
omit <dir1.dir2.---.dirN> (dir1/dir2/---/dirN/) 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.
An alternative way of guaranteeing that filenames will work on all
systems is to use the "/" style filename syntax. We prefer that form,
but it is up to you.
File: RGUIDE, Node: Output Devices, Up: Generalities, Previous: Filenames, Next: Invoking R
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.
File: RGUIDE, Node: Invoking R, Up: Generalities, Previous: Output Devices
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
File: RGUIDE, Node: Setup, Up: Top, Previous: Generalities, Next: Input
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.
File: RGUIDE, Node: Input, Up: Top, Previous: Setup, Next: Registers
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.
File: RGUIDE, Node: Registers, Up: Top, Previous: Input, Next: Expressions
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.
File: RGUIDE, Node: Expressions, Up: Top, Previous: Registers, Next: Backslash
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
File: RGUIDE, Node: Backslash, Up: Top, Previous: Expressions, Next: Justification
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
* Menu:
* Escape characters:: How to make a convenient abbreviation for a hard
to type character; how to get a text ^J, ^M, or
^L.
* Protecting:: A discussion of protected control characters;
essential for advanced work.
* Continuation lines:: How to get continuation lines -- a real
convenience feature.
File: RGUIDE, Node: Escape characters, Up: Backslash, Next: Protecting
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.
File: RGUIDE, Node: Protecting, Up: Backslash, Previous: Escape characters, Next: Continuation lines
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.
File: RGUIDE, Node: Continuation lines, Up: Backslash, Previous: Protecting
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.
File: RGUIDE, Node: Justification, Up: Top, Previous: Backslash, Next: Fonts
There are several sub-topics here, indicated in the menu below:
* Menu:
* Filling:: Fill vs. Nofill mode
This describes how R decides what to put on each output
line.
* Breaking:: What happens when R decides it is time to start a new
output line in fill mode.
* Adjusting:: This describes what R does with the stuff on an output
line once it has accumulated it. The most interesting
part is the process commonly known as justification, in
which spaces are widened to give straight edges for text
on both the right and the left.
File: RGUIDE, Node: Filling, Up: Justification, Next: Breaking
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).
File: RGUIDE, Node: Breaking, Up: Justification, Next: Adjusting, Previous: Filling, Next:
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.
File: RGUIDE, Node: Adjusting, Up: Justification, Previous: Filling
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 mode 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.
File: RGUIDE, Node: Fonts, Up: Top, Previous: Justification, Next: Macro Invocation
There are a number of different aspects of this subject:
* Menu:
* .FO:: How to tell R what fonts you want, and what fonts are.
* Switching Fonts:: How to change what font R is using.
* Selecting Fonts:: How to control what fonts the macro package will
use for various things.
File: RGUIDE, Node: .FO, Up: Fonts, Next: Switching Fonts
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)
File: RGUIDE, Node: Switching Fonts, Up: Fonts, Previous: .FO, Next: Selecting Fonts
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
File: RGUIDE, Node: Selecting Fonts, Up: Fonts, Previous: Switching Fonts
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_italic_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 table of figures and table of
tables 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.
File: RGUIDE, Node: Macro Invocation, Up: Top, Previous: Fonts, Next: Page Layout
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.
File: RGUIDE, Node: Page Layout, Up: Top, Previous: Macro Invocation, Next: Line Layout
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 reproduced 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.
File: RGUIDE, Node: Line Spacing, Up: Top, Previous: Page Layout, Next: Line Layout
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).
File: RGUIDE, Node: Line Layout, Up: Top, Previous: Line Spacing, Next: Horizontal Positioning
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.
File: RGUIDE, Node: Horizontal Positioning, Up: Top, Previous: Line Layout, Next: Text Features
There are several sub-topics here; you should definitely read the first
two. Also, you should have read node Line Layout first.
* Menu:
* Absolute Positioning:: How to get to a particular place across
the page.
* Relative Positioning:: When to use .HS instead of .HP.
* Tabs:: Using ^I (tab) and tab stops.
* Centering and Righting:: ^C and ^R in the general case.
File: RGUIDE, Node: Absolute Positioning, Up: Horizontal Positioning, Next: Relative Positioning
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.
File: RGUIDE, Node: Relative Positioning, Up: Horizontal Positioning, Previous: Absolute Positioning, Next: Tabs
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.
File: RGUIDE, Node: Tabs, Up: Horizontal Positioning, Previous: Relative Positioning, Next: Centering and Righting
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.
File: RGUIDE, Node: Centering and Righting, Up: Horizontal Positioning, Previous: Tabs
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.
File: RGUIDE, Node: Text Features, Up: Top, Previous: Horizontal Positioning, Next: Alignment
There are many interesting things you can do in text. We have gathered
together here the ones that are not discussed elsewhere.
* Menu:
* Superscripts and Subscripts::
How to do simple superscripts and subscripts,
and also more fine vertical adjustment of
characters on a line.
* Underscoring:: How to underscore text; how to control whether
white space is also underscored; all the other
details of underscoring.
* Overstriking:: How to create new characters and special symbols
by printing more than one character in the same
position.
* Hyphenation:: A description of the minimal assistance R
provides in this regard.
* Substitution:: How an arbitrary string can be substituted for a
character in the output. (More useful than it
sounds!)
File: RGUIDE, Node: Superscripts and Subscripts, Up: Text Features, Next: Underscoring
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.
File: RGUIDE, Node: Underscoring, Up: Text Features, Previous: Superscripts and Subscripts, Next: Overstriking
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. Note that the DR
(draw rectangle) request can also be used to draw lines (both vertical
and horizontal) for some output devices. See the reference manual for
details.
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.
File: RGUIDE, Node: Overstriking, Up: Text Features, Previous: Underscoring, Next: Hyphenation
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
File: RGUIDE, Node: Hyphenation, Up: Text Features, Previous: Overstriking, Next: Substitution
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.
File: RGUIDE, Node: Substitution, Up: Text Features, Previous: Hyphenation
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.
File: RGUIDE, Node: Alignment, Up: Top, Previous: Text Features, Next: Sectioning
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.
File: RGUIDE, Node: Sectioning, Up: Top, Previous: Alignment, Next: Footnotes
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.
File: RGUIDE, Node: Footnotes, Up: Top, Previous: Sectioning, Next: Figures
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.
File: RGUIDE, Node: Figures, Up: Top, Previous: Footnotes, Next: Lists
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.
File: RGUIDE, Node: Lists, Up: Top, Previous: Figures, Next: 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 extends 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.
File: RGUIDE, Node: Table of contents, Up: Top, Previous: Lists, Next: Keeping
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. It works to change toc_level in the middle of the document, so
you can show more detail or not, as the mood suits you.
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 number registers are all
normally 0 (meaning these lines are not normally produced). The font
used for the lines, and also their indentations are controlled by the
following registers of the indicated kind (number or string) and initial
value:
.nr toc_toc_font 3
.sr toc_toc_indent 0
.nr tof_toc_font 3
.sr tof_toc_indent 0
.nr tot_toc_font 3
.sr tot_toc_indent 0
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
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
(Note: if changes to big_font are to affect chapter_toc_font,
they must be performed before inserting R.MACROS. Similar comments
apply to the other font number registers.)
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.
File: RGUIDE, Node: Keeping, Up: Top, Previous, Table of Contents, Next: Setoff Things
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.
File: RGUIDE, Node: Setoff Things, Up: Top, Previous: Keeping, Next: Math
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
File: RGUIDE, Node: Math, Up: Top, Previous: Setoff Things, Next: Columnar Tables
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).
Here are good values for one real square root symbol:
.sr sqroot (-70m)#R*(+70m)
.sr sqvoff 190m
.sr sqhoff 85m
You should replace # with the designator you have chosen for
font SIGMA20. That is, the above works only if you are making a
PRESS file, and use the capital "R" of font SIGMA20 for the
square root symbol. [The above courtesy of Bill Ackerman.]
item2
^Xabove(item1 item2) - generates: item1
That is, item2 centered above item1; item1 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.
File: RGUIDE, Node: Columnar Tables, Up: Top, Previous: Math, Next: References
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. It is possible to draw
horizontal and vertical lines (using either underscoring (wins
sometimes) or .DR (much better, but available only on some devices)).
Without .DR it is non-trivial to draw vertical lines; however, BOX.RML
has some macros that you can use as is, or take as a guide. Getting
multiple ruled columns is not very easy...
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 do not
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.
File: RGUIDE, Node: References, Up: Top, Previous: Columnar Tables, Next: Writing Macros
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.
File: RGUIDE, Node: Writing Macros, Up: Top, Previous: References, Next: Debugging
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.
* Menu:
* Macro Definition:: How to define a macro, and how macro expansion
works.
* Environments:: What you should know about them, and a guide to
which things depend on the current environment,
and which do not.
* Variables and the Stack::
How to use R variables (as opposed to
registers), and the control structures.
* Macro Writer's Hints::
A collection of little suggestions and
techniques.
File: RGUIDE, Node: Macro Definition, Up: Writing Macros, Next: Environments
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.
File: RGUIDE, Node: Environments, Up: Writing Macros, Previous: Macro Definition, Next: Variables and the Stack
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.
File: RGUIDE, Node: Variables and the Stack, Up: Writing Macros, Previous: Environments, Next: Macro Writer's Hints
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.
File: RGUIDE, Node: Macro Writer's Hints, Up: Writing Macros, Previous: Variables and the Stack
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.
File: RGUIDE, Node: Debugging, Up: Top, Previous: Writing Macros, Next: Top
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.
File: RGUIDE, Node: Miscellaneous, Up: Top, Previous: Debugging
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.