3.1 Sample document, and overview

A sample SUN is illustrated in Figure 2.

Features to note:

• The document starts off with a `document type declaration', <!DOCTYPE sun PUBLIC "-//Starlink//DTD Starlink SUN//EN">, which states which DTD this document claims to be conformant to, in this case the Starlink SUN document type.
• The document is structured in terms of `element types' such as author or sect, and these in turn contain further data, such as a sequence of characters (`Norman Gray') in the case of the author element, or further elements (the version element) in the case of the history element. Elements are delimited by `opening tags' like <abstract> and `closing tags' like </abstract>.[Note 3]
• Elements have both content and attributes. For example, the author element has the characters `Norman Gray' as its content and a list of strings such as an email address as its attributes.
• Some of the elements (the abstract element for example) are closed (ie, have closing tags to match their opening tags), but the majority are not. This is because the DTD tells the parser that a title element cannot contain an author element, so the appearance of the latter implicitly finishes the former.
• Some elements and attributes are required, others optional. This document is close to being a minimal SUN. It is not quite minimal because the copyright element is optional, and it turns out that the only required content of a document body is the abstract! Also, the only required attribute of the author element is the id attribute.
• Starlink SGML documents are case-sensitive (unlike most SGML documents). The element names must all be lowercase, and SGML reserved words uppercase, as in this example.
• There are actually more elements present here than are apparent to the eye. As well as allowing some closing tags to be omitted, a DTD can be allow certain opening tags to be omitted, too. In fact, the full structure of this document is as seen in Figure 3.

In Figure 3, note that the actual content of the abstract element is one or more px elements (a slightly restricted variant of the standard p paragraph element), and that the sect element contains a subhead element, and contains the paragraphs which constitute it (note that this is a significant difference from HTML, where the heading elements hn contain only a section title). You will rarely have to be aware of these `hidden' tags when you are creating a document, but it will occasionally be useful to know that these tags are there somewhere, and that you're glad you don't have to type all of them. In fact, when I explain the document structure below, I will do it in terms of the elements which are `really' there.

`Markup minimisation', which is SGML's name for this, was introduced to SGML to make typing less onerous. Personally, I like this, since it seems to make the document look less cluttered, and so I have designed the DTD to support this quite extensively. The minimisation is completely optional, however, and you may insert all the tags if you prefer. SGML-aware editors (see Section 6.5) typically insert all tags. See also Section 3.4. XML omits this markup-minimisation feature.

You can see from Figure 3 that the `top-level' element of this document is sun. The top-level element of SSN documents is ssn, and similarly for the other Starlink document types (see Section 4.1). These different document types are broadly the same, but the SSN document type does not, by default, include elements for documenting programming code, and the MUD document type has a docdate element instead of a docnumber and a history. A particular document can re-enable such omitted features using the mechanism in Section 4.1. The SUN document type is the most general. The top-level sun element has only two `children', docinfo, which contains the document information such as its author, number, and so on, and docbody, which contains the actual content of the document.