.BG
.VE $Header: /usr3/s/current/s/.help/RCS/PROMPT,v 1.3 84/01/04 06:25:40 rab Exp $
.FN PROMPT
.FN NEWDOC
.FN EDITDOC
.FN PRINTDOC
.TL
PROMPT: Utilities for Documenting S Functions
.CS
!S PROMPT file.i ...   # UNIX command
!S NEWDOC file.d ...   # UNIX command
!S EDITDOC [\-f] name ...   # UNIX command
!S PRINTDOC [\-options] [name ...]   # UNIX command
.PP
These routines provide mechanisms to help maintain documentation for
chapters of user-written functions,
macros or datasets.
.PP
The `PROMPT' utility takes a list of files which contain interface
routines (these files have names ending in ".i").
For each "`file'.i", `PROMPT' produces an outline of documentation
on "`file'.d".
The system macro `?prompt' provides a similar facility for constructing
the outline of documentation for datasets and macros.
.PP
Each of the resulting ".d" files should be edited
with a text editor.
Within each file are a number of lines which include the character
"~" and a brief description of what should be documented
at that point.
These files use a number of `documentation macros' to control the
formatting of the printed documentation.
For example, the lines beginning ".AG" introduce function arguments;
".RC" returned components;
".FN" the names of functions documented in this file;
".TL" introduces the title;
".CS" introduces the calling sequence;
".EX" introduces lines of examples.
The documentation macro ".PP" is used to start a paragraph,
and results in a blank line in the printed documentation.
".IP topic" creates an indented paragraph that is labelled by `topic'.
These last two macros can be used to break the documentation into
appropriate paragraphs.
.PP
Once the documentation outline files have been edited, they should be
installed into the chapter documentation directory by means
of the `NEWDOC' utility.
`NEWDOC' will automatically install macro and dataset documentation into
the data directory.
Once this installation is done, the documentation will be accessible
via the `help' function as long as the chapter or data directory
are being searched.
.PP
Once the documentation is installed by `NEWDOC', the ".d" file can be
thrown away.
When it is necessary to change the documentation after it has been installed,
the utility `EDITDOC' can be used.
When given a list of documentation names, `EDITDOC' looks through the
data directory and chapter documentation for the named documents.
The documentation is then extracted and placed on file `name.d'.
This file can be edited, and then re-installed by means of `NEWDOC'.
If a function has the same name as a macro or dataset, `EDITDOC'
can be told to retrieve the function documentation by
means of the optional "\-f" flag.
.PP
The utility `PRINTDOC' is used to construct a neatly-formatted listing
of documentation.
By default, all macro and dataset documentation is printed on the user's
terminal.
If a list of names is given, the documentation
corresponding to those names is printed.
The `options' list is a set of characters preceded by a dash, and controls
the choice of output device and the listing of function documentation.
If `options' contains the character "f", documentation for functions
(rather than macros and datasets) will be printed.
The character "t" indicates that `troff' should be used to produce
final documentation on the phototypesetter.
The character "o" indicates that documentation is to be done on
an offline printer, not the terminal.
.EX
S PROMPT myfun.i
 ...  edit the file myfun.d  ...
S NEWDOC myfun.d
S PRINTDOC \-ft      # typesets all function documentation
.KW utilities
.KW UNIX
.WR
