Note for Linux Implementation by Matthew Stein

I had the whimsical notion of updating the installation documentation consistent
with the original Lloyd format, i.e. using Latex and dvips.I spent an entire day
trying to do this (a long time in my 4 courses/semester teaching position) and
it seems like its not going to work.  The circa 1992 Latex scripts are too out 
of date, since latex itself went through a major change in 1995 and is now 
Latex2e.  I have tired bo the latex2.09 emulation mode of the current tex and 
also tried putting in a few changes like changing the first line to 
"\documentclass", etc as suggested in latex conversion HOWTO's.  But although
a few pages dfo get generated there are too many errors and tex keeps halting.
Humpf...

Since the RCCL and RCI doumentation is unchanged and the installation document 
needs to be completely rewritten, it now seems hardly worth the effort to port 
the original latex documentation.  As always, I commend John Lloyd and making 
the best of what was available in 1992 (latex, I had to use this for my thesis
in 1994) but documentaiton has just moved too far beyond this to make the old 
code really worth salvaging.  I will include the 
origial latex as "legacy_" files, but will redo the installation in HTML, where 
it can be easily typed into an editor.

Here is the rest of the original README file.

This directory contains the source for the system documentation.

See the section "FILES AND DIRECTORIES" below for a description of the files
and directories. 

Almost all of the documentation is written using LaTeX, although
the RCCL and RCI reference guides use plain TeX as well. Each LaTeX or TeX
document has its own directory. There are also a few plain ascii files;
these are denoted with the file extension ".doc" and are located in
the top directory ("$RCCL/doc").

The documents are set with the assumption that your TeX system
supports a few specific features. If your TeX system does _not_
support these features, they can be switched off by modifying the
file "TeXinputs/options.tex". See the section "SPECIAL FEATURES", below.

1. DIRECTIONS FOR TeXING:

This section gives pointers on preparing output for the TeX and LaTeX
documents. LaTeX source files have the file extension ".latex"; TeX source
files have the file extension ".tex". 

1.1 Setting the Search Path for Input Files

The directory "TeXinputs" contains input files for TeX and LaTeX. Before
TeXing the documents, it will be necessary to place this directory into the
input directory search path for your TeX system. On many systems,
this is accomplished by setting the environment variable "TEXINPUTS",
as illustrated by the following example:

	setenv TEXINPUTS .:$RCCL/doc/TeXinputs:/local/TeX/lib/inputs

This creates an input directory search path consisting of the current
directory, the directory "$RCCL/doc/TeXinputs", and the standard TeX input
directory for the site, which in this case is assumed to be 
"/local/TeX/lib/inputs". 

1.2 Creating the ".dvi" and PostScript Output

You should be able to simply go to the directory for a particular document
and run

	% latex <file>.latex

This will create a ".dvi" file. Creating the ".dvi" files for the RCCL and RCI
reference manuals is slightly more complicated; see the section "RCI AND RCCL
REFERENCE MANUALS", below. 

Once you have the ".dvi" file, you then need to run a command to convert 
it into PostScript, and possibly send the result to the printer at the same
time. A common command for doing this is "dvips", which can be run as

	% dvips -o <file>.ps <file>.dvi

There are Makefiles in each TeX directory for automating these steps;
see the section MAKEFILES, below.

If your system does not support PostScript, see the next section.

2. IF YOU HAVE TROUBLE:

The document set assumes that your system supports certain features
that are not common to all TeX systems. Depending on the capabilities
of your system, these features can be disabled be editing the file
"TeXinputs/options.tex". The features are:

2.1 PostScript Fonts

By default, the documentation uses PostScript Times-Roman and Helvetica
fonts. PostScript Times-Roman is defined by the tfm files "ptmr", "ptmri",
"ptmro", "ptmb", and "ptmrc". Helvetica is defined by the tfm files
"helv", "helvi", "helvb", and "helvcsc".

If your system does not support these fonts, then replace the definition
"\@hasPsFontstrue" with "\@hasPsFontsfalse".

Alternatively, you can substitute other fonts for these by replacing 
the font definitions in the files "times.sty", "helvetica.sty",
and "manualMacros.sty". Understand that all these fonts are assumed to 
have a base size of 10 points.

2.2 Including Encapsulated PostScript

Several of the documents include figures, which are provided as
encapsulated PostScript files and included directly into the text
using the macro package "psfig.tex" (Trevor Darrell, University of
Pennsylvania).

"psfig.tex" relies to some extent on the program which converts the
".dvi" file to PostScript. If this is "dvi2ps" or "dvips", then
the package "psfig-dvi2ps.tex" should be used; if it is "dvitps",
then the package "psfig.tex" should be used. You can ensure
inclusion of the proper package by editing the definition of
"\@psfigInput".

If your system can't support psfig, then all figure inclusion can
be disabled by replacing the definition "\@hasPsIncludetrue" with
"\@hasPsIncludefalse"; these will cause the figures in the document
to be replaced with boxes of the same size. Because figures are normally
boxed anyway, you may get two nested boxes.

2.3 Slanted typewriter fonts (cmsltt10)

Not all systems seem to have the slanted typewriter font
"cmsltt". If you don't, replace the definition "\@hasSltttrue" with
"\@hasSlttfalse". 

3. THE "rccldoc" STYLE OPTION

RCCL/RCI LaTeX documents are prepared using the "rccldoc" document
style, defined in "TeXinputs/rccldoc.sty". This is a variation
on "report.sty", which contains additions specific to the McGill/McRCIM
site and to RCCL/RCI.

Options are specified inside the square brackets following the
"documentstyle" declaration at the top of the latex source file.
I will not discuss all the options here, but I will describe a few
that may be of interest.

 Type sizes:

   12pt		Specifies 12 point type size.

   11pt		Specifies 11 point type size.

   10pt		Specifies 10 point type size.

 Font selection:

   times	Specifies Times-Roman PostScript fonts
		(disabled if "\@hasPsFontsfalse" is set in "options.tex")

   helvetica	Specifies Helvetica PostScript fonts
		(disabled if "\@hasPsFontsfalse" is set in "options.tex")

   sf		Specifies cmss sans-serif fonts

		If no font style is specified, then the cmr roman fonts 
		are used.

 San-serif headers:

   sfheads	Specifies that heading titles are to be printed
		using a san-serif font instead of Roman fonts; I 
		personally think this looks better than Roman fonts
		for the large, boldface type used in heading titles.

 Typewriter font control:

   sltt		Specifies that a slanted typewriter font should be
		used instead of the regular one. This is useful if a
		sans-serif font is being used for the document, since
		otherwise the regular type-writer font may not stand out
		enough. (This is disabled if "\@hasSlttfalse" is set in
		"options.tex").

   hyphentt	Specifies that hyphenation is to be applied to text
		set in a typewriter font (which is normally *not* true).
		This may be necessary to avoid overfull boxes for documents
		that have a lot of lengthy material set in typewriter.

4. RCCL AND RCI REFERENCE MANUALS

The RCCL and RCI reference manuals live in the directories "rcclrefman"
and "rcirefman". The input files for these manuals are actually located
in the various "tex" subdirectories of "$RCCL/man", where they also
serve as source for the on-line documentation. 

Building a reference manual involves searching "$RCCL/man/tex?/*.tex"
for all the appropriate TeX files; creating a file "manpages.tex" that
includes all these sub-files in sorted order; TeXing "manpages.tex" to
create the main body of the man pages and generate the base index 
file "manpages.idx"; sorting "manpages.idx" to create "manpages.IDX",
and LaTeXing the head file ("rcirefman.latex" or "rcclrefman.latex") to create
the title pages and index listings.

Both "rcirefman" and "rcclrefman" contain a Makefile that does this
automatically; just typing

	make

in either directory will build the ".ps" and ".dvi" files necessary
for the reference manual. The Makefiles do NOT describe the dependency of the
reference manuals on the files in "$RCCL/man/tex?".

5. Makefiles

Each TeX directory contains a Makefile which automates the creation of
the documents. Typing 

	make

in any TeX directory will produce the ".dvi" and ".ps" files for the
document(s) contained in that directory. Typing

	make <docname>.dvi

will produce only the ".dvi" file.

Typing 

	make clean

will remove all the ".dvi", ".aux", ".toc", ".log", ".BAK", and ".=" files.

There is also a Makefile in the main directory "$RCCL/doc", which is
generated by imake from the source Imakefile. The Makefiles in the TeX
subdirectories are currently *not* generated by imake, although this may
change. 

Typing

	make

in "$RCCL/doc" will cause all the documents in all the TeX subdirectories
to be built.

Typing

	make clean

in "$RCCL/doc" will cause all the TeX directories to be cleaned.

The conversion of the ".dvi" file to a ".ps" file is done by a command 
described by the make variable DVIPS_CMD, which by default is set
to "dvips -o". If your system uses a different command, then it
may be necessary to change the setting of DVIPS_CMD. It is possible to do this
on the "make" command line. For instance, if the dvi-to-ps command is
"dvi2ps", then one could enter the command
	
	make DVIPS_CMD="dvi2ps -o"

This can be done either in the main directory "$RCCL/doc", or in one of 
the TeX subdirectories.

The dvi-to-ps command is set to be used in the format

	<command> <file>.ps <file>.dvi

If this is not true for your system, then it will be necessary to modify
the associated Makefile entries. 

5. FIGURES

If a document contains figures, they are contained in PostScript files 
located in a subdirectory "figs" of the document directory. Figures
are included into the document automatically when it is TeXed.

The file suffix ".eps" stands for encapsulated PostScript, and usually
denotes files generated with Aldus Freehand on a Mac. The file suffix
".idr" denotes files generated with the program X11/Interviews 
program Idraw; these are technically encapsulated PostScript as well.

6. FILES AND DIRECTORIES:

Copyright.tex
	RCCL copyright notice and disclaimer.

CtreeMatch.doc
	Describes Mike Parker's Ctree matcher, which is a set
	of routines used by interactive programs to do command completion
	and assist with parsing input.

Imakefile
Makefile
	The Makefile is used to execute large scale commands for building
	all the documentation and cleaning the directories.

TeXinputs/
	Contains .tex and .sty input files. These include:

    	Cmode.tex
		Defines plain TeX macros for setting text in
		typewriter mode, "verbatim".

	definitions.sty
		Definitions used by rccldoc.sty.

	helvetica.sty
	times.sty
	sf.sty
		Style files which implement the LaTeX documentstyles
		"helvetica", "times", and "sf", which select the fonts
		PostScript Times-Roman, PostScript Helvetica, and "cmss"
		(sans-serif), respectively.

	hyphentt.sty
		Implements the LaTeX documentstyle "hyphentt", which
		enables hyphenation for the \tt fonts.

	index.tex
		A macro package for generating index entries.

	manualMacros.tex
		Defines the various plain TeX "man" macros that are used to
		produce the manual pages for the RCCL and RCI Reference
		manuals. 
		
	options.tex
		Can be used to enable or disable certain document options,
		depending on the capabilities of a specific TeX site.

	psfig.tex
	psfig-dvi2ps.tex
		Different versions of the macro package "psfig", which
		allows a TeX document to directly insert PostScript files.
		"psfig.tex" should be used in conjunction with the program
		"dvitps", while "psfig-dvi2ps.tex" should be used in 
		conjunction with the programs "dvips" and "dvi2ps".

	psfonts.sty
		A support file for defining PostScript fonts, which is
		included by "times.sty" and "helvetica.sty".

	rccldoc.sty
		Main definition file to implement the document
		style "rccldoc".

	rdoc10.sty
	rdoc11.sty
	rdoc12.sty
		Files to implement 10pt, 11pt, and 12pt type styles
		for the documentstyle "rccldoc".

	releaseNum.tex
		Contains a string defining the current system release 
		number.

	sltt.sty
		Implements the document style "sltt", which uses slanted
		typewriter fonts in place of regular typewriter fonts.
	
binderLabels.eps
binderTabs.idr
	PostScript files containing binder labels for the two volumes of
	documentation, and tab labels for the dividers between the different
	sections. The ".idr" extension indicates a file generated with
	the X11/Interviews program Idraw.

drivers.doc
	A piece of documentation that explains the difference between
	an RCI device driver and a UNIX device driver.

errorpage.psc
	A PostScript file which, if prepended to a PostScript job, will
	cause the printer to produce an error page giving some information
	about what went wrong. This is only likely to help if you are
	a PostScript hacker, but at least you the job won't just
	mysteriously disappear on you.

hackDemoSrc
	This is a script which is used to prefilter C source code which
	is to be included into the tex documents are examples. The
	prefiltering (1) expands tabs to blanks, because the macro 
	which we use to include C source code does not like tabs, and
	(2) removes all code which is conditionalized on vxWorks.

hardware/
 	Source for the manual "RCCL/RCI Hardware Notes".

install/
 	Source for the manual "RCCL/RCI Startup and Installation Guide".

manMacros.doc
	Documentation for the manual macro package. This is a set of 
	TeX macros (yes, REAL TeX, not LaTeX) for generating man pages
	that, when run through the program texman, convert into nroff
	files. So you can have your TeX documentation and online stuff
	too.

microkernel.doc
	A description of the microkernel interface which the PUMA-LSI11
	version of "moper" runs on.

minikernel.doc
	A description of the interface to the auxiliary kernel (the
	real time kernel written for the auxiliary microVAX CPUs that
	lives in the directory "auxkernel/").

multirccl/
	Source for a paper that was submitted to the 1988 IEEE Robotics and
	Automation Conference outlining some of the features of Multi-RCCL.

obsolete/
	Miscellaneous things that are no longer very relevant.

overview/
 	Source for the manual "RCCL/RCI System Overview".

priDriver.doc
	Describes, in detail, the workings of pri driver for the DRV11
	and its counterpart in "moper". Also describes how to use
	the driver test program "driverTest".

rcclguide/
	Source for the manual "Multi-RCCL User's Guide".

rcclrefman/
	Source for the manual "Multi-RCCL Reference Manual".

rciguide/
	Source for the manual "RCI User's Guide".
	
rcipaper/
	Source for a paper, submitted to the 1990 ISRAM conference,
	describing RCI and its implementation.

rcirefman/
	Source for the manual "RCI Reference Manual".

siteList
	A list of current sites which are using RCCL/RCI; this tends
	to go out of date rather quickly.

stacktrace.doc
	A description of how to interpret the RCI stack trace on a
	microVAX system. These stack traces are generated when you get an
	exception at the RCI control level.

traject/
	Source for a paper describing the internal working of the RCCL
	trajectory generator.

updateNotes/
	Source for the document "RCCL/RCI Update Notes",
	describing the newest features that have been
	incorporated into RCCL/RCI.

uvaxKernMods/
	Source for a terse description of the changes made to uVAX 4.3 Bsd 
	UNIX to support RCCL/RCI.

