Programming with the S Documentation System

S Documentation Objects

S documentation objects are hierarchically organized, largely around elements of class "sgmlTag", the S analog of an arbitrary tag in the SGML language. These sgmlTag objects contain a tag name (a character string), attributes and a body. The attributes, if not empty, is a named object with character strings as the data elements. The body is a list, containing further sgmlTag objects and/or plain text. The recursive structure of the objects means that arbitrary SGML structure can be represented in the documentation object, allowing transformation in either direction without loss of information.

Information about rendering the documentation objects is not (wherever possible) stored in the documentation objects themselves. Instead, a (potentially extensible) set of mapping table objects contain programmatic rendering or processing information for S computations on documentation objects, and DTD tables and other non-S mechanisms can be used to control rendering or other processing once the documentation objects have been converted to SGML.

Converting to Text

The Conversion Model

The fundamental output operation in the S documentation system is to convert all or part of documentation objects to text, typically to be written to an S connection. Depending on why the conversion is being done, the form of the output will be driven by S objects, known as mapping tables. The basic function involved is
sgmlTagToText(object, maps, level = 0)
This function takes an S object, usually of class sgmlTag and a mapping table object, and returns text corresponding to the object. The function looks up the tag name of the object in a mapping table. It can find a character vector, an S function or expression, a special object of class "sgmlMap", or nothing (a null object).

What happens to the object in these cases is as follows:

expression or function
This expression is evaluated in a new frame which is constructed to contain local variables for the different components of the object being processed in processSgmlMap and the mapping table and specific map.
character string
The character string is returned as the corresponding output. For example, this is how section headings are defined in turning the documentation object into plain text for local printing.
An object of class sgmlMap.
This can contain a prefix and a suffix and a main slot which can be any legitimate map object (including an sgmlMap object itself).
NULL object
No special action for this tag, but process the body of the object, which can itself contain sgmlTag objects.
The result of evaluating the map object can be either a string or a list containing the text and the resulting object. This allows processing of the entire object and its sub-components in one step (e.g. s-usage tag) and removing the children to avoid duplicate processing.

Mapping Tables

The translation mapping table is a hierarchical structure with elements for the different documentation types. These types mirror the DTD structure in which the more specific structures include the less specific ones.
general Elements that can typically be used in any part of any document.
doc Top-level sections (e.g. s-title, etc.) and basic information for a document (version, etc.)
function Sections and structures for a document describing an S function.
class Sections and structures for a document describing an S class.
method Sections and structures for a document describing an S method. This is a simple extension of function above.
Each of these components is also a named list where the names of the elements are the SGML tag names (e.g. s-expression, code, s-section, etc.) and the elements are the objects to be returned when this tag name is matched during the conversion of an sgmlTag object to text.

SGML Tags Defined in the Mapping Table

The following table lists the SGML tags programmed in the standard mapping tables. Those found in the "general" section are included in "doc", and both these will be included in "function" and "class". Finally, "method" extends "function".
Tag NameFound InSection or Sub-section?
"application" general No
"br" general No
"code" general No
"directory" general No
"file" general No
"p" general No
"program" general No
"s-arg" function Sub
"s-args" function Yes
"s-args-optional" function Yes
"s-args-require" function Yes
"s-argument" function No
"s-author" doc Yes
"s-background" doc Yes
"s-bugs" doc Yes
"s-call" function No
"s-class" general Yes
"s-class-slot" class Yes
"s-class-title" class Yes
"s-description" doc Yes
"s-details" doc Yes
"s-docclass" doc Yes
"s-example" doc No
"s-examples" doc Yes
"s-expression" general No
"s-extends" class Yes
"s-extends-class" class Yes
"s-function-name" function No
"s-keywords" doc Yes
"s-note" doc Yes
"s-object" general No
"s-prototype-element" class No
"s-references" doc Yes
"s-section" doc Yes
"s-see" doc Yes
"s-side-effects" function Yes
"s-signature" method Yes
"s-signature-arg" method Sub
"s-slots" class Yes
"s-title" doc Yes
"s-topics" doc Yes
"s-usage" function Yes
"s-usage-expression" function Yes
"s-value" doc Yes
"s-warning" doc No
"s-warnings" doc Yes
"url" general No
Documentation Tags

Duncan Temple Lang<>
Last modified: Fri Jun 19 16:55:55 EDT 1998