The Starlink SGML set supports people writing Starlink documents, such as SUNs, SSNs, MUDs and the like.[Note 1] It consists of a definition of a markup language suitable for such documents, plus software to convert these source documents to reader-friendly form. At present, these `output formats' include HTML and LaTeX (and hence include postscript and PDF formats).
The SGML set scores over previous solutions to Starlink's
documentation needs, such as runoff or LaTeX, because it is a
well-defined system, so that there is excellent support for it in
tools, and it is designed to be converted into whichever presentation
format is most convenient.
The DTD is designed to be flexible, rather than imposing a
particularly tight document structure. At the same time it has
enough structure that it can be indexed and stored effectively.
Although this system can help with many of the tasks involved in document creation, it cannot write the document for you (shame!). For advice on that, documents such as SGP/28 are still vital.
This document is organised as follows. In Section 2, we
discuss SGML in general terms, describing its general structure and
aims, why it was chosen as the format for the Starlink document set, and
pointing to sources of information. In Section 3, we describe
how you would go about actually writing a document, describing the
structure of Starlink documents which is crystallised in the
specification of this set. In Section 4, we describe the
structure of the document DTD, and the categories of elements you will use.
In Section 5, we describe the
support which exists to support documentation of source code, allowing
you to maintain detailed routine documentation along with the routine
source code. In Section 6, we describe the details of how
you transform your document from SGML to an output format. In
Section 7 we describe how to transform a document from
star2html format to an SGML document.
Finally,
the appendices give the detailed descriptions of the elements in the
two DTDs described here, a more detailed description of SGML than is
necessary for simple use of the set, and documentation for
maintainers of the set.