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
different 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 ele‐
ments. The organization and structure of a document and the meaning of
elements are described in the Document Type Definition ( DTD ). Ele‐
ments 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 sub‐
set 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 struc‐
ture 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 -awareman(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 equiva‐
lent to the name of the reference page's file name,
without the section number extension.
<manvolnum> This is the section number that the reference page
resides in. The contents may be a text entity refer‐
ence.
<refmiscinfo> There are one or more <refmiscinfo> tags which contain
meta information. Meta information is information about
the reference page. The <refmiscinfo> tag has the
class attribute. There are four classes that are rou‐
tinely used.
date This is the date that the file was last
modified. By consensus this date is
changed only when the technical infor‐
mation on the page changes and not sim‐
ply for an editorial change.
sectdesc This is the section title of the refer‐
ence page; for example User Commands.
The value of this attribute may be a
text entity reference.
software This is the name of the software prod‐
uct 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 lim‐
itation of the subject discussed on the
reference page. If there are no limita‐
tions the value used is generic. Other
values are sparc and x86.
copyright This attribute contains the Sun
Microsystems copyright. Any other copy‐
rights that may pertain to the individ‐
ual 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 dis‐
cussed on the same page. In this case the first tag
after the <refnamediv> is a <refdiscriptor>. The <ref‐
name> 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 dif‐
ferent 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 cat‐
egories.
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 ref‐
erence.
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 head‐
ing 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 charac‐
ter such as a bullet or a dash.
<literallayout> Formatted program output as produced by a pro‐
gram 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 sig‐
nificant.
<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 refer‐
ences to books other than the reference manual.
<xref> A cross reference to another part of the same
reference page.
SEE ALSOman(1), nroff(1), man(5)SunOS 5.10 7 Jan 1997 sgml(5)
