|
Hopefully, this page is exactly what you are looking for, but if not, you can always find further assistance on Unix/Linux Forum!
Standards, Environments, and Macros 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
SunOS 5.10 Last change: 7 Jan 1997 1
Standards, Environments, and Macros sgml(5)
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 refer-
ence page resides in. The contents may be a
text entity reference.
<refmiscinfo> There are one or more <refmiscinfo> tags
which contain meta information. Meta infor-
mation 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 techn-
ical 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
SunOS 5.10 Last change: 7 Jan 1997 2
Standards, Environments, and Macros sgml(5)
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 indivi-
dual 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.
SunOS 5.10 Last change: 7 Jan 1997 3
Standards, Environments, and Macros sgml(5)
<refpurpose> The text after the dash on the NAME line is
contained in this tag. This is a short sum-
mary 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 gen-
eral topic descriptor of a group of related
objects that are discussed on the same page.
In this case the first tag after the <ref-
namediv> is a <refdiscriptor>. The <refname>
tags follow. Only one <refdiscriptor> is
allowed, and it should match the <refen-
trytitle>.
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
SunOS 5.10 Last change: 7 Jan 1997 4
Standards, Environments, and Macros sgml(5)
<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 para-
graph of text.
<variablelist> This tag is used to create two
column lists. For example descrip-
tions 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>.
SunOS 5.10 Last change: 7 Jan 1997 5
Standards, Environments, and Macros sgml(5)
<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 con-
tains a required <title>.
<informalexample> This tag is the same as the <exam-
ple> 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 exter-
nal 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.
SunOS 5.10 Last change: 7 Jan 1997 6
Standards, Environments, and Macros sgml(5)
<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 Last change: 7 Jan 1997 7
Man(1) output converted with
man2html and wrapped by fishsponge
This page was generated on Wed Sep 12 11:27:58 GMT 2007
|
Your favourite pages:
No pages logged yet.
Trying to save cookie... Top 10 most popular pages:
CPAN man page (4333 hits)
(Suse Linux 10.1)
ssh man page (4186 hits)
(Suse Linux 10.1)
adv_cap_autoneg man page (4146 hits)
(Solaris 10 11_06)
sqlite3 man page (4069 hits)
(openSUSE 10.2)
svn man page (3249 hits)
(FreeBSD 6.2)
startproc man page (1908 hits)
(Suse Linux 10.1)
pprosetup man page (1666 hits)
(Solaris 10 11_06)
netcat man page (1613 hits)
(Suse Linux 10.1)
signal man page (1592 hits)
(Suse Linux 10.1)
ssh-socks5-proxy-connect man page (1558 hits)
(Solaris 10 11_06)
|
Man Pages 
