Overview of the S Documentation Engine
We briefly describe the different stages in the
life of an S documentation object and the associated
tools for each phase.
This material is covered in more detail in Chapter 9 of Programming with Data.
The steps below show how to create a documentation object and provide programmers
with the necessary background
information to customize the output.
Generating the Document
In most cases, we create the initial documentation object
using the self-documenting feature in S4.
We do this with the S expression
dumpDoc("topic")
where topic is usually the name of a function. See the book or
the online documentation of dumpDoc for options.
This creates a file containing the documentation provided
in the object and the default fields the developer may complete.
Editing the Document
Arbitrary text can be inserted into the elements
of the document using a standard editor. We use
emacs (currently with
html-helper-mode) to add
HTML-like elements.
The permissible SGML elements
are described in
Writing Documentation
Creating the S object
To create the S documentation object
in the S system from the ASCII input file,
give the command
sourceDoc('file-name')
Converting Documentation to Target Format
Currently, the documentation object can be converted
into SGML, HTML and plain text representations.
However, adding new targets such as TeXinfo, TeX/LaTeX,
man pages, etc. is also conceptually easy.
The first is trivial, involving only printing
of the document - show(getDoc('object-name').
The other conversions involve translating the SGML elements
into `commands' in the target language.
The functions
printDoctargetname()
are used to do this conversion and utilize a
named table of translation mappings.
To create mappings for a new target, one can
simply copy the
object textMappings and edit its contents
as needed.
If new elements/tags are added to documentation structure,
corresponding entries should be added to each of the
top-level mapping objects.
Duncan Temple Lang<duncan@research.bell-labs.com>
Last modified: Fri Jun 19 10:45:07 EDT 1998