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
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

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