sgml(5)
NAME
sgml, solbook - Standard Generalized Markup Language
DESCRIPTION
Standard Generalized Markup Language (SGML) is the ISO stan-
dard 8879:1986 that describes a syntax for marking up docu-
ments with tags that describe the purpose of the text rather
than the appearance on the page. This form of markup facili-
tates 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 elements. The organization and structure of a docu-
ment and the meaning of elements are described in the Docu-
ment 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 para-
graphs. 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 ele-
ment is defined and a framework is provided for the types of
elements that constitute 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 stan-
dard 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 Sol-
Book 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 <!DOC-
TYPE 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 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 con-
tain meta information. Meta information is information
about the reference 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 modi-
fied. 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 gen-
eric. Other values are sparc and x86.
copyright
This attribute contains the Sun Microsystems
copyright. Any other copyrights that may pertain
to the individual 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> con-
tains 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 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 <ref-
synopsisdiv> as a sub-section heading for the SYNOPSIS sec-
tion.
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 exam-
ple 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 refer-
ence page.
SEE ALSO
man(1), nroff(1), man(5)
Man(1) output converted with
man2html