Trailing-Edge
-
PDP-10 Archives
-
mit_emacs_170_teco_1220
-
info/rmacro.info
There are no other files named rmacro.info in the archive.
This is the file containing the INFO-ized documentation on using
R with its standard macro package.
File: RMACRO 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 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.
* 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 layout:: How R lays out each input line, and
macro package facilities for setting
line margins.
* 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.
* 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: RMACRO, 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: RMACRO, 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 (and DOVER, coming soon)
XGP XGP XGPSEND
LPT TPL
If there are error messages, or the document does not have the
desired appearance, you back back to step 1, and create a new
input file that you think will work better. It may take doing
this half a dozen times to get rid of the "bugs" in a new
version of a document.
R normally prints its error messages on your terminal as it
runs. However, it is often better to save them in a file, so
that you don't have to write down what is on your screen to
avoid losing the messages. See the section on invoking R for
information on how to do this.
Some of the other text formatters available are:
(Opinions expressed are mine, but I have found many experienced
users to agree with most of these statements.)
SCRIBE - has approximately the same capabilities as R,
and about the same strong and weak points.
Easier for the novice to use than R, but maybe
harder for the expert to get what s/he wants.
Can do single or multiple pass processing.
Not available on ITS at this time, maybe never.
TJ6 - a very simple minded, easy to use formatter, with
superficial similarities to R. Most people find
TJ6 too simple: there are too many things it
cannot do. Available only on ITS.
PUB - a powerful but often arcane formatter. Slower
than R, but it can do a few more things than R
can. Available only on ITS.
TEX - Good for mathematical things like equations and
tables, but not as easy to use as some of the
other formatters. Not as convenient as other
formatters on non-mathematical documents.
Available only on ITS
In sum, R may not be for you. But you should know that R is the
only text formatter we have that runs under all our computer
systems.
The diagram of the document preparation process that we drew
above is overly simple: sometimes one processes the input text
some before giving it to R, and sometimes one processes the
output file some before printing it out. An example of the
first situation is this: you can run a spelling checking and
correcting program (e.g., ISPELL) to find spelling errors
before running R. Some examples of the second situation are:
you may use a program that extracts only the pages that have
changed between versions of a document (e.g., @ or XGPDIFF), or
you may have to run RALP on line printer output (see node
Devices).
File: RMACRO, 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 in preparation by another person (Judi Jones).
That document should complement this one, in that the Primer is
something you can sit down and read all at once. This guide go
farther, and is therefore longer. We recommend that most parts
be skimmed on first reading. Having two different explanations
of the same thing should help; we have tried hard to make sure
that the two documents do not say contradictory or wrong things.
Documentation on the macro package consists of this file, and
also R;RMACRO INFO (<R>RMACRO.INFO on XX -- from now on, assume
the XX name is the one corresponding to the ITS name unless
told otherwise). Either file may be printed on your terminal or
a line printer. (This file is INFO;RMACRO INFO.) The other
file may be retired if this one works out.
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: RMACRO, 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
In the .so command of R, you may
omit device: if it is DSK:
omit directory; if it is your directory, or R;
omit name2 if it is >, R, or RMAC
In the .fo command of R, you may
omit device: if it is DSK:
omit directory; if it is your directory, FONTS;,
FONTS1;, FONTS2;, XFONT;, or R;
omit name2 if it is KST
NOTE: In the command line, filenames may NOT have spaces
in them. Thus, ':r foo >' will NOT do what you might
expect! However, the second name need not be given if
it is R, RMAC, or >. If you must supply a second name,
there are two ways:
:r "foo bar" -- put the file name in double quotes
The other way involves a different format of filenames,
and is explained in the reference manual.
On TOPS-20:
Full filenames on TOPS20 have the form:
device:<directory>name1.name2.version
In the .so command of R, you may
omit device: if it is DSK:
omit <directory> if it is your directory or PS:<R>
omit name2 if it is R or RMAC
omit version it is the most recent one (0)
In the .fo command of R, you may
omit device: if it is DSK:
omit directory; if it is your directory,
PS:<FONTS>, PS:<FONTS1>, PS:<FONTS2>,
PS:<XFONT>, or PS:<R>
omit name2 if it is KST
omit version if it is the most recent one
NOTE: To make files more easily portable from system to system,
you should try to arrange things so that you can omit the
device, directory and name2 fields in as many cases as
possible. R was purposely designed to make this easy in most
cases. For example, unless you made up a font file yourself
and gave it a funny name, you never need to state the device or
directory for a font. Similarly, it is conventional to set
your input file's name2 to be > on ITS (R on XX), and to use a
name2 of >, R, or RMAC for auxiliary input files. If you do
so, then you will not have to state the name2 to R. Since
almost all files will be in your directory or the R directory,
this means that most of the time you need only state the name1
of the desired file. In the cases where you need name2,
writing the filename as name1.name2 works on all systems.
There is no nice way to include a directory or device that can
be read on all systems with no changes. Therefore, we suggest
that you omit as many of the filename fields as you can.
File: RMACRO, 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. Capabilites 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: RMACRO, 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: RMACRO, 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: RMACRO, 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.
File: RMACRO, Node: Registers, Up: Top, Previous: Input, Next: Backslash
R has NUMBER REGISTERS and STRING REGISTERS, which are very
useful. It is hard to give an easy to understand explanation
of exactly how they work, but they turn out to be easy to use
in the common situations. Let us consider an example.
Say that you find you are typing ^F5^Q^N^F... quite a lot,
because it is a special character used many times in your
document. Let us say that it is a summation sign (capital
sigma). You can define a string register to give you a handy
abbreviation for that:
.sr sum ^F5^Q^N^F*
Then, wherever you want the summation sign to appear, just
write "^Ssum". The .SR command ("string register") has two
ARGUMENTS, a name for the string register ("sum" in this case),
and the stuff to put in it. The name begins after the space
after the .SR, and continues to the next space. Register names
(this holds for number registers, too) can have only these
characters in them: A through Z, 0 through 9, and _. Case
(upper or lower) is ignored.
The stuff that goes into a string register starts with
the first non-space, non-tab character and continues to the end of the
line. If you need the first character of the stuff in a string
register to be a space or a tab, precede it by a backslash. For
example: .sr foo \ abc
The above puts space, a, b, c into the string register FOO. If
you want to set a string register so that it has nothing in it,
then just put nothing after its name, e.g.: .sr foo
Whereas as string registers hold strings (a technical name for a
bunch of characters), number registers hold numbers. Number
registers hold whole numbers (integers) only, and positive and
negative numbers are allowed. The biggest number you can put
into a number register depends upon what computer system you are
using, but is always at least 15000. As we saw before, the
contents of a string register can be made to appear by typing ^S
followed by the string register name. To get the value of a
number register to appear, we use ^N followed by the number
registers name. Similarly, we use .nr to set a number register.
Here is a simple example:
.nr foo 105
The serial number of the stolen item was ^Nfoo.
what will appear in the output is:
The serial number of the stolen item was 105.
The paritcular 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.
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: RMACRO, Node: Backslash, Up: Top, Previous: Registers, 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: RMACRO, 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: RMACRO, 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 nmber 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: RMACRO, 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 any
that is useful for except continuation lines.
File: RMACRO, Node: Justification, Up: Top, Previous: Backslash, Next: Fonts
Not filled in yet.
File: RMACRO, Node: Fonts, Up: Top, Previous: Justification, Next: Macro Invocation
Not filled in yet.
File: RMACRO, Node: Macro Invocation, Up: Top, Previous: Fonts, Next: Page layout
Not filled in yet.
File: RMACRO, Node: Page layout, Up: Top, Previous: Macro Invocation, Next: Line layout
Not filled in yet.
File: RMACRO, Node: Line layout, Up: Top, Previous: Page layout, Next: Alignment
Not filled in yet.
File: RMACRO, Node: Alignment, Up: Top, Previous: Line layout, Next: Sectioning
Not filled in yet.
File: RMACRO, Node: Sectioning, Up: Top, Previous: Alignment, Next: Footnotes
Not filled in yet.
File: RMACRO, Node: Footnotes, Up: Top, Previous: Sectioning, Next: Figures
Not filled in yet.
File: RMACRO, Node: Figures, Up: Top, Previous: Footnotes, Next: Lists
Not filled in yet.
File: RMACRO, Node: Lists, Up: Top, Previous: Figures, Next: Table of contents
Not filled in yet.
File: RMACRO, Node: Table of contents, Up: Top, Previous: Lists, Next: Setoff Things
Not filled in yet.
File: RMACRO, Node: Setoff Things, Up: Top, Previous: Table of contents, Next: Math
Not filled in yet.
File: RMACRO, Node: Math, Up: Top, Previous: Setoff Things, Next: Columnar Tables
Not filled in yet.
File: RMACRO, Node: Columnar Tables, Up: Top, Previous: Math, Next: References
Not filled in yet.
File: RMACRO, Node: References, Up: Top, Previous: Columnar Tables, Next: Writing Macros
Not filled in yet.
File: RMACRO, Node: Writing Macros, Up: Top, Previous: References, Next: Debugging
Not filled in yet.
File: RMACRO, Node: Debugging, Up: Top, Previous: References, Next: Top
Not filled in yet.