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 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 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 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 section 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 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 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 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> 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,SEEALSO,
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.