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

Documentation Tags
Tag Name	Found In	Section 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

Duncan Temple Lang <duncan@research.bell-labs.com>

Last modified: Fri Jun 19 16:55:55 EDT 1998