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
                                  file,  the  place  of  R  in the document
                                  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.
                                  knowledge is necessary  for  you  to  get
                                  other  than  the  default  actions of the

          * 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
                                  arguments, etc.

          * Page Layout::         How  the  standard macro package lays out
          the page
                                  into vertical sections (top margin,  text
                                  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
                                  package   facilities   for  setting  line

          * Horizontal Positioning::
                                  How to control fine positioning of  items
          on the
                                  output line.

          * Text Features::       This  discusses  a raft of little, useful
                                  such   as   super-   and    subscripting,
                                  overstriking, output translation, and

          * Alignment::           How  to  get things on different lines to
          line up
                                  vertically in various ways.

          * Sectioning::          The macros  available  for  organizing  a
                                  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

                                  The list facility is quite flexible and

          * Table of contents::   How to get a table of contents,  and  how
                                  control its appearance.

          * Keeping::             How  to keep things on a single line or a

          * Setoff Things::       Here we describe the facilities available
                                  setting things off in the text.  Examples
                                  this  kind  of  thing   are   quotations,
                                  program   text,   and  various  kinds  of
          pictures and

          * Math::                Here we describe the facilities available
                                  doing    mathematical    equations    and
          formulae, and
                                  give  some hints on how to go beyond what
                                  standardly available.

          * Columnar tables::     Introduction to methods of making  tables
                                  consist  of vertical columns that must be
                                  in a particular way.

          * References::          Introduction to  the  packages  available
                                  producing    bibliographies   and   keyed
          references in
                                  running text.

          * Writing Macros::      Conventions and hints on macro writing in
                                  general.  Specific  hints  are  given  in

          * 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
          * Documentation::       What  is  available and where to find it.
          How to
                                  report bugs.  How to get on  the  mailing

          * Filenames::           Things  you should know about how R deals

          * Output Devices::      Things you should know  about  using  the
                                  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
                          to use than R, but maybe harder for the expert to
                          what s/he wants.  Can do single or multiple pass
                  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
                  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
                  TEX - Good for mathematical  things  like  equations  and
                          but  not  as  easy  to  use  as some of the other
                          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

          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:

          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

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

          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

          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
                  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
                                  FONTS;, FONTS1;, FONTS2;, XFONT;, or R;
                          omit name2 if it is KST
                  NOTE:  In the command line, filenames may NOT have spaces
                  them.  Thus, ':r foo  >'  will  NOT  do  what  you  might
                  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
                  The  other  way  is  to  use  the "/" form of file-names,

          On TOPS-20:
                  Full filenames on TOPS20 have the form:
                  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, put  >  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,