Trailing-Edge
-
PDP-10 Archives
-
mit_emacs_170_teco_1220
-
info/rguide.lpt
There are no other files named rguide.lpt 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,