.BG
.VE $Header: /usr3/s/current/s/.help/RCS/CHAPTER,v 1.4 84/01/05 06:03:39 rab Exp $
.FN CHAPTER
.FN MAKE
.FN FUNCTION
.TL
CHAPTER: Utility Commands to Maintain a Chapter of S Functions
.CS
!S CHAPTER   # UNIX command
!S FUNCTION  [options] name files ...   # UNIX command
!S MAKE name   # UNIX command
.PP
A user's chapter of S functions is initialized (once) under the
current UNIX directory by executing the command `CHAPTER'.  Each time a
new S function is to be written, the `FUNCTION' command is used (once).
Whenever the function has been changed (either the interface routine
or any of the other files on which the function depends), the `MAKE'
command is used.
.PP
.AG options
options controlling the interface to the function: a
concatenation of any of the following: `\-g' for a graphics
function; `\-r' for a function which needs to read the system
common blocks (for example, because it does printing on
OUTFC or generates random numbers)
`\-w' for a function which modifies the system
parameters, and so must write the system common blocks
(strongly discouraged for user functions), and `\-d' for
a device-driver function.
.AG name
the name of the S function. 
There should be a
corresponding interface routine on a file `name.i' in the
current directory.
.AG files
names of files on which the function depends (in addition to
standard S libraries), including the interface routine file
`name.i', source files (which must end in ".r", ".f", ".C", or ".c")
or library files.
The `MAKE'
command will try to keep up-to-date with source files, and
will simply include all other files in the command that
loads the function.
.PP
The `CHAPTER' utility creates subdirectories named "x" and ".help" in the
current directory, as well as a file "Smakefile".
Subdirectory "x" will contain the executable versions of any functions
created in the chapter; ".help" contains the detailed documentation for
each function in the chapter.
The `FUNCTION' utility updates
file "Smakefile", so that it contains file names and commands
for creating functions in the chapter.
.PP
Whenever `MAKE' is executed, it follows the "Smakefile" rules
to create the executable file in subdirectory "x".
In the process, it also creates object files,
whose names end in ".x" and ".o", from the source files.
These object files can be removed as soon as a satisfactory version
of the function has been created.
The file "i.`name'.C" is an intermediate file and can also be removed safely.
.PP
It is the user's responsibility to keep up-to-date any libraries,
object files, etc. that are not given to `FUNCTION' as source files.  If
for some reason, the function must be reloaded even though none of the
files on which it depends has been modified, precede the `MAKE' command
by the UNIX command `rm name'.
.PP
If the set of files on which the function depends changes; e.g.,
the function now depends on a new ".r" file, the correct FUNCTION
command should be given. This is the only time that FUNCTION must
be re-invoked.
.KW utilities
.KW UNIX
.WR
