sgml(5) Standards, Environments, and Macros sgml(5)
NAME
sgml, solbook - Standard Generalized Markup Language
DESCRIPTION
Standard Generalized Markup Language (SGML) is the ISO standard 8879:1986 that describes a syntax for marking up documents with tags that
describe the purpose of the text rather than the appearance on the page. This form of markup facilitates document interchange between dif-
ferent platforms and applications. SGML allows the management of information as data objects rather than text on a page.
In an SGML document the main structural components are called elements. The organization and structure of a document and the meaning of
elements are described in the Document Type Definition ( DTD ). Elements are the tags that identify the content. Element names may be
descriptive of the content for ease of use. For example <para> for paragraphs. Elements can have attributes which are used to modify or
refine the properties or characteristics of
the element. Within the DTD a valid context for each element is defined and a framework is provided for the types of elements that con-
stitute a compliant document.
Another component of the DTD is entities. Entities are a collection of characters that can be referenced as a unit. Entities are similar
to constants in a programming language such as C. They can be defined and referenced. An entity can represent one character or symbol
which does not appear on a standard keyboard, a word or group of words, or an entire separate sgml marked-up file. Entities allow reuse of
standard text.
There is no single standard DTD , but the de facto standard for the computer industry is the DocBook DTD , developed and maintained by
the Davenport Group. Within Sun, the SolBook DTD , which is a proper subset of DocBook DTD , is used when writing reference manual pages.
The SolBook DTD contains a number of tags that are designed for the unique needs of the reference pages.
SolBook Elements
Elements are defined with a hierarchical structure that gives a structure to the document. The following is a description of some of the
elements from the SolBook DTD which are used for reference pages.
DOCTYPE
The first line in an SGML file that identifies the location of the DTD that is used to define the document. The <!DOCTYPE string is what
the
SGML -aware man(1) command uses to identify that a file is formatted in SGML rather than nroff(1).
RefEntry
The top layer element that contains a reference page is <refentry>. All of the text and other tags must be contained within this tag.
RefMeta
The next tag in a reference page is <refmeta>, which is a container for several other tags. They are:
<refentrytitle> This is the title of the reference page. It is equivalent to the name of the reference page's file name, without the sec-
tion number extension.
<manvolnum> This is the section number that the reference page resides in. The contents may be a text entity reference.
<refmiscinfo> There are one or more <refmiscinfo> tags which contain meta information. Meta information is information about the refer-
ence page. The <refmiscinfo> tag has the class attribute. There are four classes that are routinely used.
date This is the date that the file was last modified. By consensus this date is changed only when the technical
information on the page changes and not simply for an editorial change.
sectdesc This is the section title of the reference page; for example User Commands. The value of this attribute
may be a text entity reference.
software This is the name of the software product that the topic discussed on the reference page belongs to. For
example UNIX commands are part of the SunOS x.x release. The value of this attribute may be a text entity
reference.
arch This is the architectural platform limitation of the subject discussed on the reference page. If there are
no limitations the value used is generic. Other values are sparc and x86.
copyright This attribute contains the Sun Microsystems copyright. Any other copyrights that may pertain to the indi-
vidual reference page file should be entered as separate <refmiscinfo> entries. The value of this
attribute may be a text entity reference.
RefNameDiv
This tag contains the equivalent information to the .TH macro line in an nroff(1) reference page. <refnamediv> contains three tags. These
tags contain the text that is before and after the `-' (dash) on the NAME line.
<refname> These are the names of the topics that are discussed in the file. There may be more than one <refname> for a page. The
first <refname> must match the name of the file and the <refentrytitle>. If there are more than one <refname> tags, each is
separated by a `,' (comma). The comma is generated by the publisher of sgml files, so it should not be typed. This is
referred to as auto-generated text.
<refpurpose> The text after the dash on the NAME line is contained in this tag. This is a short summary of what the object or objects
described on the reference page do or are used for. The dash is also auto-generated and should not be typed in.
<refdiscriptor> In some cases the <refentrytitle> is a general topic descriptor of a group of related objects that are discussed on the
same page. In this case the first tag after the <refnamediv> is a <refdiscriptor>. The <refname> tags follow. Only one
<refdiscriptor> is allowed, and it should match the <refentrytitle>.
RefSynopsisDiv
The SYNOPSIS line of the reference page is contained by this tag. There is a <title> that usually contains an entity reference. The text is
the word SYNOPSIS. There are several tags within <refsynopsisdiv> that are designed specifically for the type of synopsis that is used in
the different reference page sections. The three types are:
<cmdsynopsis> Used for commands and utilities pages.
<funcsynopsis> Used for programming interface pages.
<synopsis> Used for pages that do not fall into the other two categories.
RefSect1
This tag is equivalent to the .SH nroff macro. It contains a <title> element that is the title of the reference page section. Section
names are the standard names such as DESCRIPTION, OPTIONS, PARAMETERS, SEE ALSO, and others. The contents of the <title> may be a text
entity reference.
RefSect2
This tag is equivalent to the .SS nroff macro. It contains a <title> element that contains the text of the sub-section heading. <refsect2>
tags may also be used within a <refsynopsisdiv> as a sub-section heading for the SYNOPSIS section.
Block Elements
There are a number of block elements that are used for grouping text. This is a list of some of these elements.
<para> This tag is used to contain a paragraph of text.
<variablelist> This tag is used to create two column lists. For example descriptions for command options, where the first column
lists the option and the second column describes the option.
<orderedlist> An list of items in a specific order.
<itemizedlist> A list of items that are marked with a character such as a bullet or a dash.
<literallayout> Formatted program output as produced by a program or command. This tag is a container for lines set off from the
main text in which line breaks, tabs, and leading white space are significant.
<programlisting> A segment of program code. Line breaks and leading white space are significant.
<table> This tag contains the layout and content for tabular formatting of information. <table> has a required <title>.
<informaltable> This tag is the same as the <table> tag except the <title> is not required.
<example> This tag contains examples of source code or usage of commands. It contains a required <title>.
<informalexample> This tag is the same as the <example> tag except the <title> is not required.
Inline Elements
The inline elements are used for tagging text.
<command> An executable program or the entry a user makes to execute a command.
<function> A subroutine in a program or external library.
<literal> Contains any literal string.
<parameter> An argument passed to a computer program by a function or routine.
<inlineequation> An untitled mathematical equation occurring in-line.
<link> A hypertext link to text within a book, in the case of the reference manual it is used to cross reference to
another reference page.
<olink> A hypertext link used to create cross references to books other than the reference manual.
<xref> A cross reference to another part of the same reference page.
SEE ALSO
man(1), nroff(1), man(5)
SunOS 5.10 7 Jan 1997 sgml(5)