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