Writing S Documentation

The S documentation, when mapped into SGML, uses some special SGML tags (in addition to the tags normally allowed in HTML documents). These tags relate to the structure of the documentation, that is, to its meaning in terms of what it describes, of particular concepts in S, etc. In contrast, the rendering decisions are largely independent of these tags, and are defined by style sheets and/or other tags included in the document.

Top-Level Structure

The documentation object is structured as sections (effectively, named elements of the object). A number of sections are pre-defined, depending on the documentation class (e.g, "function" or "class"). Other arbitrary sections can be added.

S Expressions as SGML

The documentation library in S includes the ability to map an arbitrary S expression into an SGML structure that reflects the S object. In other words, instead of just producing a text representation of the expression, this approach reproduces the full structure of the S expression. You can benefit from this structure if you want to do computations that understand something about that structure (e.g., treating particular S syntactic structures such as for loops in a special way). Most of the time, you don't want to edit the resulting SGML directly, but instead to provide the S object to an S function that generates the SGML.

Tags Generated from S Expression Objects
Tag Class(es)
"s-assign-expr" "=", "<-", "<<-"
"s-for-expr" "for"
"s-while-expr" "while"
"s-repeat-expr" "repeat"
"s-if-expr" "if"
"s-paren-expr" "("
"s-brace-expr" "{"
"s-name-expr" "name"
"s-function-expr" "function"
"s-formalArgs-expr" Any
"s-formalArg-expr" Any
"s-call-expr" "call"
"s-unaryOp-expr" "call"
"s-binaryOp-expr" "call"
"s-arg-expr" Any
"s-literal-expr" Any non-language

Duncan Temple Lang<duncan@research.bell-labs.com>
Last modified: Fri Jun 19 15:27:57 EDT 1998