Whole document tree
Reference Entries
RefEntry is a specialized section intended to contain reference material for a software construct. Its content model is much stricter than that for sections. It is intended to accommodate traditional UNIX™ man pages and other similar structures. In order create a "true" man page, you should supply a value for the ManVolNum element in the RefMeta element corresponding to the man page's traditional section number (and optional suffix).
RefEntries may be organized as collections, for example, by including them in sections of Chapters or in References.
RefEntry contains, in fixed order, an optional DocInfo, an optional RefMeta, any number of Comments or elements from the %link.char.class;, a RefNameDiv, an optional RefSynopsisDiv, and one or more RefSect1s.
RefEntry Metainformation
DocInfo and RefMeta are intended for document metainformation, whereas RefNameDiv should contain metainformation about the software construct being described.
RefMeta contains, in fixed order, a RefEntryTitle, an optional ManVolNum, and any number of RefMiscInfo elements. RefMiscInfo is intended to store special information associated with traditional man pages (such as chip architecture, original vendor or distributor, and so on, which often appear in printed man page headers and footers). The Class attribute may be used to subclass the kind of information supplied; interchange partners must agree on the Class attribute values that are meaningful to them.
RefNameDiv contains, in fixed order, an optional RefDescriptor (for a generic name grouping several software constructs), one or more RefNames (for each construct being documented), a RefPurpose (for permuted indexes and quick lookup of reference information), any number of RefClasses (for describing the applicability of the software construct or constructs on different system configurations), and any number of comments or elements from the %link.char.class;.
RefEntry Content
RefSynopsisDiv may be used to contain synopsis information that can be assembled into a quick reference that can be processed separately. It has roughly the same model as RefSect1, as synopsis information can come in all sorts of packages. It contains an optional Title, an optional TitleAbbrev, one or more object-level components from the %ref component.mix; mixture, and any number of RefSect2 elements. If there is no Title, it is assumed that a standard title (such as "Synopsis," "Syntax," or "Format") will be generated on output.
Three levels of reference section are provided: RefSect1-3. For a traditional man page structure, use RefSect1 Title elements to indicate each top-level section, such as Description, Options/Flags, and References/See Also.
The RefSect elements contain a Title, an optional TitleAbbrev, one or more object-level components from the %ref.component.mix; mixture, and any number of lower-level reference sections (in the case of RefSect1 and RefSect2).