Many - perhaps most - Starlink documents exist to describe a body of program code, and while the general behaviour and usage of that program can be described in a document such as this one, the details of the implementation might be most sensibly kept with the program code itself. The Starlink DTDs have facilities to do precisely this, associating documentation directly with program code, and associating that detailed documentation with user documents.
As described in Section 4.4, the Starlink General DTD has an element routinelist, containing one or more codecollection elements. Each of these latter elements makes a link between the documentation and a document marked up using the programcode DTD, which I will now describe.
If you wish to refer to some element within the codecollection, say
a function to which you gave the ID myfunc by specifying an
`id' attribute to a routine or
routinename programcode
element, you do so via the `codecollection' element. You
make the reference using the coderef
element, which takes two attributes: an ID for the
`codecollection' which contains the programcode file, and (required)
the name of the ID within that file. For example (assume entities
`myfiles' and `origfiles' have been declared as subdocuments,
referring to programcode documents):
Notice that the `codecollection' element provides a sort of namespacing, so that you don't have to worry about having to give different IDs to functions in different collections of code.<p>See also <coderef collection=mystuff id=myfunc>my funky function</coderef>, and compare it with <coderef collection=theirstuff id=myfunc>their silly subroutine</coderef>. [...] <sect>All the code <routinelist> <p>Here's the beef <codecollection id=mystuff doc=myfiles> <codecollection id=theirstuff doc=origfiles>
The programcode document - the document marked up using the programcode DTD, pointed to by the main documentation - may be a conventional SGML document, maintained separately or generated from idiolectal source markup by some sed or Perl magic, or it may be a skeleton document which includes separate (compilable) source files into itself. It makes no difference to the SGML parser, but gives the code author flexibility in deciding how much, and what, markup to allow into their code comments.
There are distinct document type declarations for the different supported languages, although they use the same underlying markup. This is so that the generic programcode DTD can be slightly customised as appropriate for different languages. See Section 5.2.
The programcode DTD is more elaborate than it could have been. Different people have different coding and documenting styles, and are firmly wedded to them, so I felt that flexibility was more important than simplicity. As a result, there is sometimes more than one place where information can reasonably be placed. Also, the DTD makes it possible to exploit tag-omission quite heavily (see Section 3.4) - the aim was to indicate an adequate level of structure using as little markup as possible.
The programcode DTD is designed to document code; there is no reason why it could not also be used to prettyprint it, by taking a marked-up document and putting it through a different processor. That, however, is a project for another time.