Guide to the DocBook DTD DTD release 2.1>
Documentation version 1.3 for release 2.1,
7 May 1994
HaL Computer Systems International, Ltd.>
O'Reilly & Associates, Inc.>
1992
1993
1994
HaL Computer Systems International, Ltd.>
O'Reilly & Associates, Inc.
Permission to use, copy, modify and distribute the
DocBook DTD and its accompanying documentation for any
purpose and without fee is hereby granted,
provided that this copyright notice appears in all copies.
HaL Computer Systems and O'Reilly & Associates make no
representation about the suitability of the DTD for any
purpose. It is provided “as is” without expressed or
implied warranty.
Please direct all questions, bug reports, or suggestions for changes to davenport@ora.com or by mail to
either: Terry Allen, O'Reilly & Associates, Inc.,
103A Morris Street, Sebastopol, California, 95472; or
Conleth O'Connell, HaL Computer Systems, 3006–A Longhorn
Blvd., Austin, Texas, 78758.
Acknowledgements>
The DocBook DTD is a joint effort of
Hal Computer Systems International, Ltd., and O'Reilly &
Associates, Inc.
Conleth O'Connell and Terry Allen are the current design
team for the DTD; Con deserves special mention as chief
architect. Through several revisions,
a lot of other people at both companies contributed
their insight and encouragement, particularly Steve Williams
and David Bass of HaL Computer Systems, and Dale
Dougherty of O'Reilly & Associates. Special mention for
help with this revision goes to Eve Maler of Digital Equipment
Corporation (synopses and good general advice)
and Bryan Caporlette of Passage Systems (CALS table model).
How to Get the DocBook DTD Online
You can find the DocBook DTD and its documentation
online in the Davenport archive
(/pub/davenport/docbook) at
ftp.ora.com (140.186.65.25).
This sample session shows how to retrieve the DTD
and its documentation:
%>ftp ftp.ora.com>
Connected to ruby.ora.com.
220 ruby FTP server (Version 6.12 Thu Apr 23 21:09:30 EDT 1993) ready.
Name (ftp.ora.com:dale): anonymous>
331 Guest login ok, send e-mail address as password.
Password: ← type e-mail address>
ftp>>cd pub/davenport/docbook>
The DocBook DTD and related ASCII files are in
a file named docbook.N.shar>, where N>
is the current revision number:
ftp>>get docbook.2.1.shar>
Most of these files
also exist separately and may be ftp'd individually.
The get> command will put this ASCII shar
file on your system. You must later unpack
it on your system:
sh docbook.2.1.shar>
Back to your ftp session. The DocBook documentation
is in a compressed PostScript file:
ftp>>binary>
ftp>>get docbook.ps.Z>
This puts the binary file docbook.ps.Z> on your system.
You must uncompress it before sending it to a PostScript
printer or viewer.
Development of the DocBook DTD
The DocBook DTD defines structural SGML markup for computer
documentation and technical books. It is supported by
the Davenport Group, which is a group of software
documentation producers that was established to promote
the interchange and delivery of computer documentation
using SGML and other relevant standards.
Our primary goal in developing this DTD was to filter
existing software documentation into SGML. It describes the
structures we and other producers and consumers of software
documentation have encountered in processing large bodies of
such material. While it was initiated as an interchange
format, the DTD is now coming into use as a production DTD.
Accordingly, in this revision,
specific processing expectations have been
developed for some elements, and some print
conventions are modelled more directly than before.
We expect that this DTD will evolve as it is applied to more
documents, as more SGML tools come into use, and as users
gain more experience in working with it. We are interested
in your use of the DocBook DTD and welcome comment
(see title page for addresses). We are committed to reviewing
revisions made by various groups and
evaluating them for inclusion in the next release.
Groups using the DocBook DTD
for material other than software documentation may need
to extend it for their domain of applications.
Likewise, anyone may wish to construct a subset of this
DTD, or a local version that constrains authors more
tightly.
Before making changes you should read the section
near the top of the DTD itself regarding
local modifications.
A Structural View of the DTD
The DTD uses the model of books to represent the content
of documentation. The primary metainformation about a
collection of documents is located at the Book level.
A collection of Books can be a Set, but no larger
structures are provided. A Book is composed
of book components, such as Prefaces
and Chapters and Appendices, some of which may be
organized in Parts.
Below these book components are additional
levels of sectioning, marked as Sect1 through Sect5.
A section is further organized by block-oriented
elements such as Paras (paragraphs). Other
block-oriented elements, such as lists, are
more complex, requiring other elements within them.
For example, a Listitem (an item in
a list) may contain more than one paragraph, and lists
may be nested within Listitems.
In addition to its hierarchical organization, the information
may be marked up with elements that indicate nonlinear
relationships, including IndexTerms, XRefs (cross references),
and Links.
This DTD also provides many general and specific in-line
elements, some of which are peculiar to computer documentation.
The following sections show examples of
how to combine the syntactic elements defined
in the DocBook DTD.
Following these examples is a reference section with brief
definitions of all the elements.
SGML element names are not
case-sensitive. We capitalize them for readability.
In the examples that follow,
some punctuation and math characters are represented by
text
entities (for example, &>), which are defined
by external reference in the DTD.
A few elements appear in various contexts;
for example, Title is used for
the contents of headings at all levels.
The typography of the examples is designed for legibility;
line breaks and leading white space are not
significant.
In some elements the dreaded SGML mixed
content is allowed, but should be benign. The following
warning should no longer be needed:
For best results start the text of an element
immediately after the start tag, without a space or line
break.
Some attributes are not mentioned in the following
description. For full details
on attributes, see the alphabetical list of elements.
Sets, Books, and Their Parts
Here's a diagram of a fairly vanilla Book:
Book
BookInfo
ToC
LoT
Preface
Chapter
Chapter
Chapter
Chapter
Reference
Appendix
Appendix
Glossary
Bibliography
Index
Books may have Chapters and Appendices grouped in
Parts:
Book
BookInfo
Preface
Part
PartIntro
Chapter
Chapter
Part
PartIntro
Chapter
Chapter
Chapter
Part
PartIntro
Chapter
Chapter
A reference manual might be
arranged like this:
Book
BookInfo
ToC
LoT
Preface
Reference
Reference
Reference
Reference
Appendix
Appendix
Appendix
Appendix
Index
A Set of Books may
have a SetInfo and must contain two or more
Books:
Set
SetInfo
Book
Book
Book
In a change from the previous revision, the all-purpose
DocBook wrapper has been retired. Now, in order to
parse your document, you must specify its highest-level
element at its head, in the
document type declaration:
!DOCTYPE chapter SYSTEM "/anyold/path/docbook.dtd"
or construct a shell file that contains a document type
declaration, and refers to your document as an entity.
In this case, your document should have no document type
declaration itself.
In this example a short Book is represented, with
its later parts commented out:
<!DOCTYPE book SYSTEM "/anyold/path/docbook.dtd"
[
!ENTITY bookinfo SYSTEM "/some/path/bookinfo.sgm"
!ENTITY pref SYSTEM "/some/path/pref.sgm"
!ENTITY c1 SYSTEM "/some/path/ch01.sgm"
!ENTITY c2 SYSTEM "/some/path/ch07.sgm"
!ENTITY appa SYSTEM "/some/path/appa.sgm"
!ENTITY appb SYSTEM "/some/path/appb.sgm"
!ENTITY glossary SYSTEM "/some/path/glossary.sgm"
]>
BOOK
&bookinfo;
&pref;
&c1;
!-- &c2; --
!-- &appa; --
!-- &appb; --
!-- &glossary; --
/BOOK
>
A Book may begin with a Title and TitleAbbrev
(abbreviated title), followed in order by an optional
BookInfo, an optional ToC (Table of Contents),
any number of LoTs (List of Titles), any number of Prefaces,
main contents, and back matter.
The main contents are
required, and must be one or more Parts;
one or more Chapters followed by any
number of References;
one or more Articles; or one or more References.
All back matter is optional, but must appear in order:
any number of Appendices,
a Glossary, a Bibliography, and any number of Indexes
and SetIndexes,
followed by any number of LoTs, followed by an optional
ToC.
Book has FPI and Label attributes; you can supply an
SGML Formal Public Indentifier (FPI) as the value of
the former
and the number of a Book, when it is part of a Set, in
the latter. The Label attribute, which is provided for
book parts, too, allows you to “take a snapshot” of
a document collection, or to use one particular state
of it for reference. The Mark attribute on OrderedList
and the BeginPage element provide further means to
do this. You might want to use these elements to
ensure that an on-line presentation of your
document collection
can be matched to a print version by standard
reference methods (citing chapter number, number of
an item in a list, page number).
Part contains an optional DocInfo, a required Title, an optional TitleAbbrev, an optional PartIntro,
followed by one or more book components.
You can use book components individually.
For example, here is a Chapter standing
on its own:
Chapter
Title
TitleAbbrev
Para
Para
BOOK
CHAPTER ID="CH-061-ch05-1"
TITLEAn Introduction to the X Window System
/TITLE
TITLEABBREVIntro to X
/TITLEABBREV
PARAAnd so on.
.
.
.
/PARA
/CHAPTER
/BOOK
>
Preface, Chapter, Appendix, Bibliography,
Glossary, and Index
A Chapter or Appendix
may have a DocInfo, followed by a required
Title and some text at least a Sect,
a paragraph, a list, or a RefEntry. It may also have a
TitleAbbrev. The DocInfo may contain information
relevant to that book part alone; information general
to the collection(s) of which it is part should be
placed in the collection(s)'s BookInfo(s).
A Preface, Glossary, or Bibliography must have a Title,
so you can use the Preface element for a foreword or
acknowledgements section
and call a Glossary or Bibliography something else, such as
“Key Words,” or “Sources.”
Bibliography, Glossary, and Index are also allowed to have
more specialized contents: BiblioEntry for Bibliography,
GlossEntry for Glossary, and IndexEntry for Index.
These specialized book parts may be divided
into BiblioDivs, GlossDivs, or IndexDivs, respectively.
(An IndexEntry is part of an Index, whereas
an IndexTerm is part of the text of a document, marking the
term to be indexed.) Additionally, an IndexDiv may have
a SegmentedList, to accommodate permuted indices. A Glossary may end with a Bibliography.
IndexEntries and IndexTerms are discussed later.
BiblioEntries may begin and end with BiblioMisc,
between which there must be an ArtHeader, BookBiblio,
or SeriesInfo. This makes it possible to use the
same content model for metainformation and bibliographic
reference. (In the future there should perhaps be some way
to link from a BiblioEntry to a BookBiblio somewhere
on one's local system.)
GlossaryEntries are simply pairs of GlossaryTerms
and GlossaryDefs, both of which may contain
in-line elements.
Bibliography, Glossary, Reference, and
Index may be book components on their own or
may occur at the beginning
or end of a Preface, Chapter, Appendix, or Sect.
A RefEntry (the element for a man page) cannot be
a book component, but can appear in the same places within
Preface, Chapter, Appendix, or Sect as can a
Bibliography, Glossary, or Index.
You could construct a Chapter this way:
Chapter
Title
Para
Sect1
Title
Para
Para
Para
Glossary
Bibliography
Sect1
Title
RefEntry
RefEntry
RefEntry
RefEntry
Index
Table of Contents
A ToC, or table of contents, may be
a book component on its own or may
occur within other book components. It may
have a DocInfo, Title, and TitleAbbrev. In this revision,
ToC has been subdivided to follow the divisions of a book:
following an optional Title and
TitleAbbrev, a ToC may have any number of ToCFronts, which
are the entries for the front matter. Following the
ToCFronts, if any, a ToC must have either
one or more ToCParts (entries for Parts)
or ToCChaps (entries for Chapters and Appendices),
and may have any number of ToCBacks
(entries for back matter).
A ToCPart may begin with in-line elements (in all
cases, this part is the
actual table of contents
entry, which was formerly ToCEntry), then contains
any number of ToCChaps. Like other ToC subelements,
it has a PageNum attribute, which may have the
value of a physical page
number. A ToCChap may begin with
in-line elements, then may have any number of ToCLevel1s,
which are entries for Sect1s.
ToCLevel1s may begin with in-line elements, then may have
any number of ToCLevel2s, and so on down to ToCLevel5,
which may have only in-line elements. Thus if you have a
Table of Contents that shows section headings,
the second-level entries
are nested within the first-level entries, and so on.
Alternately, a Link may be included as all or
part of the contents of a
ToC subelement, both pointing to a section by its ID and
containing (as text) the page number on which the section
begins. For example:
TOC ID="CH-061-toc-1"
TITLETable of Contents
/TITLE
TOCCHAP LINKEND="S1-061-ch01-1"Chapter One: Nuts and Bolts
/TOCCHAP
TOCCHAPChapter Two: Screws and Nails
TOCLEVEL1Screws
/TOCLEVEL1
TOCLEVEL1Nails
/TOCLEVEL1
/TOCCHAP
/TOC
Notice that you can make a ToC into a small model of a
Book, a facility that could be used to provide context
to an application that may be called upon to
process an arbitrary piece of a Book without access to
the other pieces. This facility is duplicated in BookInfo's
Contents attribute, and the ToC must be considered along
with any LoTs and the BookInfo to provide fuller context.
Lists of Titles (LoT)
An LoT is like a ToC except that it is used for
lists of tables, figures, and so on. An LoT contains LoTEntries,
which may contain Links, just like ToC subelements.
LoTEntries also have a PageNum attribute,
but have no subelements.
BookInfo and DocInfo
A BookInfo contains metainformation about the collection
of documents of which it is a part. BookInfo
must contain a BookBiblio (a wrapper, new in this
revision, for any information that might appear in
a bibliographic reference),
followed by any number of LegalNotices,
followed by any number of ModeSpecs (which
are link processing information sets,
pointed to by the LinkMode attribute of OLink,
and collected here for common reference).
BookInfo has a Contents attribute, the
values of which are the IDs of the ToC, LoTs,
Prefaces, Parts, Chapters, Appendixes, References,
Glossary, Bibliography, and Indexes
comprising the Book, in the order of their appearance.
BookBiblio contains all the information about a book
that may be relevant
to a bibliographical citation, so that
it may also be used or referred to by BiblioEntry.
In fact, all the information typically found on a
title page's recto and verso are included in BookBiblio,
except the LegalNotices, although only Title and AuthorGroup
are required. BookBiblio may contain, in order:
the required Title (the title of the Book),
optional TitleAbbrev,
Subtitle, and Edition, followed by one or more required
AuthorGroups; then, optionally, either an ISBN followed
by an optional VolumeNum (the number of the volume in
a Set) or (in case you are using Book for a journal
composed of Articles) an ISSN followed by
optional VolumeNum, optional IssueNum, and an
optional PageNums (the numbers of the pages contained in
a given issue or volume). After these elements there may
occur, again optionally and in order, the labelling
information InvPartNumber, ProductNumber, ProductName,
PubsNumber, and ReleaseInfo.
Then there may be any number
of Pubdates followed by any number of Publishers,
followed by an optional
Copyright, then an optional SeriesInfo (information
about a series the Book is published as part of).
Following that there may be any number of
Abstracts, any number of ConfGroups (wrappers for
information about a conference from which the Book
results), any number
of ContractNums mixed with any number of ContractSponsors,
and an optional
PrintHistory followed by an optional RevHistory.
An individual book component may have a DocInfo,
in which information pertinent only to that component
may appear. DocInfo may contain, in order:
a required Title, optional TitleAbbrev and
Subtitle, followed by one or more
AuthorGroups, any number of
Abstracts, an optional RevHistory, and any number of
LegalNotices.
References
A Reference is a collection of RefEntries. Before
its RefEntries, it has an optional DocInfo,
a required Title, an optional TitleAbbrev,
and an optional PartIntro. It may be a book component or
may occur within a Part.
For example:
Reference
Title
PartIntro
RefEntry
RefEntry
RefEntry
RefEntry
RefEntry
Sections (Heads)
A Preface, Chapter, or Appendix may contain
up to five levels of hierarchical sections called Sect1, Sect2, and so on.
In a RefEntry, these are RefSect1 through RefSect3
(no further subheads). Headings must be
nested properly: a Sect3 is not allowed
directly under a Sect1 without a Sect2 in between.
Sects1--4 that contain lower-level Sects
may be empty of other content. However, a Bridgehead
(a heading not contained in a wrapper that associates
it with the text following, and independent of the
Sect hierarchy)
may be inserted between block-oriented elements anywhere,
with its RenderAs attribute set to an appropriate value.
In this revision, the Docbook DTD no longer
allows you to put paragraphs, lists, and other
block-oriented
elements between Sects.
A section includes a Title
(the text of the heading itself) and all material
following, up to the end of the document or the next section at the same or higher level.
Consequently, anything may occur in a section except another
book component (DocInfo, Glossary, and
so on) or another section of the same level; deeper
sections must be nested properly.
SECT1 ID="S1-061-ch05-1"
TITLERunning the Program
/TITLE
PARAIf you have the sample programs
and a workstation that runs X, you can try out this program
by compiling FILENAME>basic/basicwin.c</FILENAME.
/PARA
/SECT1
>
Sections have a Number attribute, in case you wish to
hard-code section numbering for reference.
Block-Oriented Elements
Most book components can contain the following
block-oriented elements, some of them in formal
and informal dress. Informal elements such as
InformalTable are simply untitled equivalents
of their formal sisters (Table), and are not to
be listed in a LoT (such as a List of Tables).
Highlights (list of main points)
an Epigraph
Paragraphs
Lists
Procedures
MsgSets (error messages)
Admonitions (Warnings, Tips, and so on)
Tables and InformalTables
Figures and Equations
Examples
LiteralLayouts, ProgramListings, Screens, and ScreenShots
Graphics
BlockQuotes
Sidebars
Footnotes
Admonitions and other blocks
Highlights and Epigraph
An Epigraph (a section of poetry or prose, usually
specially formatted) may occur between a book component's
Title and other content.
Highlights (a section of major points appearing in the book
component) typically appears below either the Title (or
below any Epigraph), or may be extracted and presented
before book component proper begins.
Paragraphs
Paragraphs are the lowest level of
ordinary text that you need to tag except for
in-line elements. The DocBook DTD offers three kinds of paragraphs.
Para may contain block-oriented elements
(for example, Footnotes, lists, and Figures), while SimPara excludes
them. FormalPara requires a Title, while Para and
SimPara may not have Titles.
FormalPara, Para, and SimPara are allowed in exactly
the same contexts. No provision is made, in the case of
SimPara, for indicating indentation; in the case of
FormalPara and Para it is not needed.
In some cases, such as admonitions and Footnotes,
paragraph tags are required within the outer tags, to allow
multiple paragraphs. Thus a paragraph may be nested within
a paragraph if a wrapper intervenes.
WARNING
PARANever use software from sources
you would not trust with your firstborn.
/PARA
PARAIf in doubt about a program, don't use it at all.
/PARA
/WARNING
Lists contain ListItems, which typically contain
paragraphs; ListItems, too, may contain more than one
paragraph. (See List examples below.)
Aside from straight text and, in the case of
SimPara, block-oriented elements,
paragraphs may contain any of the in-line
elements discussed
in the “In-line Components” section.
Lists
There are five kinds of lists:
ItemizedList (bulletted, dashed, and so on)
OrderedList (numbered or lettered)
VariableList (composed of paragraphs or sets of paragraphs
with associated Terms)
SegmentedList (a series of entries composed of equal
numbers of segments, with optional titles pertaining
to all the first segments, all the second segments,
and so on)
SimpleList (composed of terms that may be arranged in columns
or in-line)
Lists may be
nested within ListItems (an ItemizedList inside a ListItem
of an OrderedList, for example),
and ListItems may include paragraphs and other block-oriented
elements.
ItemizedLists use the Mark attribute to determine the
character that precedes each ListItem. You may leave
this to an application to decide, or supply a
text string (there is no default and there are no
generally agreed upon strings) to specify the mark that
should appear before
each ListItem. You might use such
strings as Bullet, Dash, Box, or Check, or a text
entity instead (such as bull>). The Mark
value can be overridden at the ListItem level
by the value of the ListItem's Mark attribute,
if it is supplied.
Here's an ItemizedList:
ITEMIZEDLIST MARK="DASH"
LISTITEM
PARAThis function should connect the client to an X server with\break
FUNCTION>XOpenDisplay</FUNCTION,
and exit gracefully if the connection could not be made.
/PARA
/LISTITEM
LISTITEM
PARAGet information about the physical screen, and use it to
calculate the desired size of the window.
/PARA
PARAA second paragraph occurring
within the same dashed ListItem would be marked up as this
paragraph is.
/PARA
/LISTITEM
/ITEMIZEDLIST
>
Normally an ItemizedList nested within a list of
the same type is given a different mark or alphanumeric
style (as in an outline).
The DocBook DTD does not define any default sequence of marks.
You must either indicate them by using the appropriate
attributes or instruct your SGML application that, for example, the
sequence of marks for an
ItemizedList that contains another ItemizedList is
bullets, then dashes.
OrderedLists may use the Numeration attribute to
determine how the list is numbered. This attribute
has a delimited set of values:
Arabic (1, 2, 3), Upperalpha (A, B, C), Loweralpha
(a, b, c), Upperroman (I, II, III), or
Lowerroman (i, ii, iii). If extensions are needed, for example in the
case of Japanese or Arabic documents, the values
LocalAlpha and
LocalNumber might be used, though these are not now
supported.
The default is Arabic. If your numbered list begins with
1, you do not need to supply a Numeration value.
OrderedList
also has the Continuation attribute, to
indicate whether the numbering of a list begins afresh or
continues the numbering of the immediately preceding list.
Finally, OrderedList has an InheritNum attribute, the values
of which are Inherit and Ignore. Ignore is the default;
i.e.>, numbering
starts over (1, 2, 3 instead of 3.1, 3.2, 3.3).
Set InheritNum to Inherit if you want nested lists to
pick up the numbering of the ListItem within which they
are nested (an OrderedList nested under the
third ListItem of another OrderedList is numbered
3.1, 3.2, 3.3, instead of 1, 2, 3).
ORDEREDLIST
LISTITEM
PARA>The window is mapped with <FUNCTION>XMapWindow</FUNCTION or related routines.
/PARA
/LISTITEM
LISTITEM
PARAAll its ancestors must be mapped. This
condition is always satisfied for the children of the root
window, the top-level windows of each application.
/PARA
/LISTITEM
LISTITEM
PARAThe window must not be obscured by visible
sibling windows or their
ancestors this depends on the stacking order. When first
mapped, a window appears on top of its siblings, which will
be on top of all windows if its parent is the root window.
/PARA
/LISTITEM
/ORDEREDLIST
A VariableList may have a Title and TitleAbbrev,
and must have VarListEntries, each of which
contains a set of
one or more Terms followed by
a ListItem. Terms may contain in-line
elements. Schematically a VariableList looks like this:
VariableList
VarListEntry
Term
Term
ListItem
Para
Para
VarListEntry
Term
ListItem
Para
VarListEntry
Term
ListItem
Para
In actual markup:
VARIABLELIST
VARLISTENTRY
TERMWindow
/TERM
LISTITEM
PARAA unique integer identifier (ID) that is
returned by XCreateWindow or XCreateSimpleWindow and is
thereafter used by the program to refer to the created
window resource.
/PARA
/LISTITEM
/VARLISTENTRY
VARLISTENTRY
TERMDisplay
/TERM
LISTITEM
PARAA large structure that contains information
about the server and its screens. It is filled only after
this program connects to a server by calling XOpenDisplay.
/PARA
PARAA small structure containing information about
the server and its screens would be more economical, but we
mention it only to generate another paragraph.
/PARA
/LISTITEM
/VARLISTENTRY
/VARIABLELIST
A SegmentedList is composed of labelled
sets of information,
and may be used to represent information
that is often presented in simple tables. A SegmentedList
may have a Title and TitleAbbrev, followed by any number of
SegTitles and two or more SegListItems. SegListItems
are composed of two or more Segs, which may contain
in-line elements. You might render a SegmentedList
in tabular form, or use some other typographic arrangment,
such as:
SEGMENTEDLIST
SEGTITLEMuseum
/SEGTITLE
SEGTITLECity
/SEGTITLE
SEGTITLECollections
/SEGTITLE
SEGLISTITEM
SEGAsian Art Museum
/SEG
SEGSan Francisco
/SEG
SEGEast Asian, Indian, and Islamic
/SEG
/SEGLISTITEM
SEGLISTITEM
SEGBritish Museum
/SEG
SEGLondon
/SEG
SEG><EMPHASIS>all areas</EMPHASIS
/SEG
/SEGLISTITEM
SEGLISTITEM
SEGLouvre
/SEG
SEGParis
/SEG
SEGmostly paintings
/SEG
/SEGLISTITEM
/SEGMENTEDLIST
This SegmentedList might appear in print as follows:
Museum: Asian Art Museum
City: San Francisco
Collections: East Asian, Indian, and Islamic
Museum: British Museum
City: London
Collections: all areas
Museum: Louvre
City: Paris
Collections: mostly paintings
A SimpleList is intended for long lists of single words
or short phrases. It consists of one or more Members, and
has Columns and Type attributes.
The value of Type may be Vert (the default),
Horiz, or Inline. Inline indicates that the list
should be formatted as a regular part of a paragraph,
with commas and “and” inserted, such as:
a, b, c, d, e, f, g, h, i, j, k,> and l.>
Vert and Horiz indicate that the Members
should be displayed in the number of columns
specified by the Columns attribute (the default
is 1). If the value of Type is Vert, the Members should be
ordered from top to bottom of each column:
a d g j
b e h k
c f i l
If Horiz,
the Members should be ordered left to right, one row at
a time:
a b c d
e f g h
i j k l
Procedures
A Procedure is a quasilist of operations to
be performed. Procedure may have a Title and
TitleAbbrev, followed by block-oriented elements,
such as paragraphs, followed by one or more Steps.
A Step may have a SubSteps wrapper for Steps nested
within it, and this nesting may continue indefinitely
(contrast the methods of nesting lists and Sects).
This construction is intended to maximize the reusability
of subsections of Procedures.
Note that “SubSteps” is an element name,
not the plural of SubStep (there is no element named
SubStep).
After an optional Title, a Step must consist either
of block-oriented elements such as
paragraphs followed optionally by a SubSteps element,
or simply a
SubSteps element. A SubSteps then contains one or more
Steps it is a wrapper.
PROCEDURE
TITLE>Waking Up</TITLE
PARAThis is what you must do to awaken.
/PARA
STEP
PARABring yourself to a hypnopompic state, either from an
ongoing dream or by use of your internal clock. You may
feel unable to move, but you will no longer be dreaming.
/PARA
PARANow you are ready for real-world readjustment.
/PARA
SUBSTEPS
STEP
PARARoll over.
/PARA
/STEP
STEP
PARASquint out of one eye.
/PARA
/STEP
/SUBSTEPS
/STEP
STEP
PARAYawn and rise from your bed.
/PARA
/STEP
/PROCEDURE
MsgSet
A MsgSet is a quasilist of messages produced
by a system, with various additional information.
These are typically error messages, but they
could conceivably be congratulatory
or soothing messages to the user.
Please note that the entire Msg*
construction is new and complicated;
it may be simplified in the future.
MsgSet contains one or more MsgEntries, which
are merely wrappers, each containing
one or more Msgs, followed by an optional
MsgInfo, then any number of MsgExplans.
Msg is the part of a MsgEntry that contains
the error message and its subparts, along with
explanatory text. A Msg has a required MsgMain,
followed by any number of MsgSubs and MsgRels, in any
order.
MsgMain is the main error message of a
Msg. MsgMain begins with an optional Title,
followed by MsgText, the real content of the message
(containing may be block-oriented elements).
MsgSub contains messages that appear in various
contexts. It, too,
contains a an optional Title followed by
MsgText. MsgRel contains
a message that is related to the main message
(MsgMain) but which appears in a
different place. For example, MsgMain
might be a message that appears on a
network client, and MsgRel a related message
that appears at the
server console in response to the same condition or event.
MsgRel begins with an optional Title and contains
MsgText.
That finishes the Msg part of MsgEntry; there remain
MsgInfo and MsgExplan.
MsgInfo holds information about the Msg
containing it. It may have any number of MsgLevels,
MsgOrigs, and MsgAuds, in any order.
MsgLevel describes, in plain text,
the level of importance or severity
of a Msg. MsgOrig describes, in plain
text, the origin of a Msg.
MsgAud describes, again in plain text, the audience
to which a Msg is
relevant.
MsgExplan is a holder for any kind of explanatory
material relating to the
Msg. MsgExplan begins with an optional Title
(typically something such as
“Explanation:” or “Action:”)
and may contain block-oriented elements.
MSGENTRY
MSG
MSGMAIN
MSGTEXT
PARAAuto removal: Token-ring lobe
/PARA
/MSGTEXT
/MSGMAIN
MSGSUB
TITLEFailure
/TITLE
MSGTEXT
PARALocal token-ring adapter
/PARA
PARALocal access unit
/PARA
PARALocal lobe cables
/PARA
/MSGTEXT
/MSGSUB
MSGREL
TITLENetWare message:
/TITLE
MSGTEXT
PARA>TOKEN-NW-237-Adapter <REPLACEABLE>number</REPLACEABLE> -board <REPLACEABLE>number</REPLACEABLE : The adapter
is beaconing.
/PARA
PARA>Ring status = <REPLACEABLE>code</REPLACEABLE .
/PARA
/MSGTEXT
/MSGREL
/MSG
MSGINFO
MSGORIGNetView for NetWare
/MSGORIG
MSGLEVELInformative
/MSGLEVEL
/MSGINFO
MSGEXPLAN
TITLEExplanation:
/TITLE
PARAAdapter left the ring as part of the beacon automatic
recovery process.
/PARA
/MSGEXPLAN
MSGEXPLAN
TITLEAction:
/TITLE
PARAAsk the LAN administrator to review the link data.
/PARA
/MSGEXPLAN
/MSGENTRY
>
Tables
A Table is an ordered array of text, usually with a title
and headings. This information may be represented in SGML,
but it may also be convenient to provide it in
another form. The DocBook
DTD allows you to mark up a table in SGML and also provide
a graphic representation of it in an external file
by using the Graphic element.
Aside from Graphic,
DocBook's Table formerly offered a choice of a simple
model or a version of the
canontbl.dtd, copyright SoftQuad, Inc. (used
by kind permission of Yuri Rubinsky, SoftQuad).
However, as no general solution to table markup seems
to have been developed, and the CALS MIL-28001
DTD is more widely supported by existing
tools, DocBook now permits only Graphic or a CALS-compliant
model. If it is any consolation, the canontbl.dtd
uses much of the same structure as CALS, easing migration
from one model to the other.
A Table has a required Title, a TitleAbbrev, and one or more
Graphics (which may be
pointers to external files that contain the Table formatted
in a different way) or one or more TGroups, which are
slabs of CALS table. For details on the contents of
Table see the alphabetical list of elements; Tables may
not be nested within Tables, but a Table may contain
an EntryTbl, which achieves the same effect.
InformalTable is Table's untitled sister.
For Graphic, see Figure,> below.
TABLE
TITLESample Decimal-Aligned Table
/TITLE
TGROUP ALIGN="CHAROFF="50"CHAR="." COLS="3"
TBODY
ROW
ENTRY>345.021</ENTRY
ENTRY>211.02</ENTRY
ENTRY>221.3</ENTRY
/ROW
ROW
ENTRY>blue</ENTRY
ENTRY>red</ENTRY
ENTRY>yellow</ENTRY
/ROW
/TBODY
/TGROUP
/TABLE
>
Figures and Equations
A Figure must have
a Title, may have a TitleAbbrev, and may contain
one or more of the following: BlockQuote,
InformalEquation, Graphic,
InformalTable, Link, LiteralLayout,
OLink, ProgramListing, Screen, Synopses, and ULink.
A Graphic may contain graphical data or point to exterior
files that contain such data. It
has an ID attribute
and a Format attribute that indicates how the
data is formatted. Format may have the value
CGM-CHAR, CGM-CLEAR, DITROFF, DVI, EPS,
EQN, FAX, FAXTILE, GIF, IGES, PIC, PS, TBL, TEX,
TIFF. There is no
default. Graphic may point to an external file via
its Fileref or Entityref attributes. The value of
Fileref should be a filename; the value of
Entityref should be that of an
external data entity. These attributes may conflict,
so an order of precedence is specified:
if data is given as the
content of Graphic, neither Entityref nor Fileref
should be given but a Format value should be supplied.
If no data is given as the content of
Graphic, only one of Entityref
Fileref should be given; if both are present,
Entityref pre\"empts Fileref. If either
of those attributes is used, Format should not be.
If Graphic occurs within or between paragraphs,
it is to be displayed as a block (that is,
Graphic is an informal figure);
if a graphical image is to be presented in-line,
it must be marked as an
InlineGraphic, which is otherwise just like Graphic.
Figure has common,
Label, and Float attributes; Float indicates
whether the Figure is to be rendered
where convenient (yes) or at
the place it occurs in the text (no, the default).
FIGURE ID="FG-061-ch05-2" FLOAT="YES"
TITLEThe xdmlogwin Display
/TITLE
GRAPHIC ENTITYREF="gr061ch05t2"
/FIGURE
>
Equations are solely graphical in this revision.
An Equation may have a Title and TitleAbbrev, and
then contains one or more InformalEquations
or Graphics, in any order. InformalEquation
is an untitled equation to be displayed as a block,
like InformalTable, and may contain one or more
Graphics; it has common attributes. InlineEquation
is just the same as InformalEquation, but is to
be display in-line.
Examples
Example is defined very loosely, so that
a program listing can be accompanied by other
block-oriented elements.
An Example must have a Title, may have a TitleAbbrev,
and then contains any combination of paragraphs,
lists, and other block-oriented elements.
LiteralLayouts, ProgramListings, Screens,
and ScreenShots
The DocBook DTD provides three elements for material
set off from the main text, in which
white space and line breaks are to be considered
significant: LiteralLayout, ProgramListing, and
Screen. All of these elements
may contain in-line elements only, not
block-oriented elements. They all have a Width
attribute, which is some number indicating to an
application how wide the widest line is, and
a fixed Format attribute, with the value “linespecific.”
LiteralLayout is the simplest of the linespecific elements.
It consists only of the set-off lines:
PARAFor information about the U.N. and intergalactic space, ask
LITERALLAYOUT
Butros Butros Ghali
Secretary General
United Nations
/LITERALLAYOUT
about the Security Council's jurisdiction over the Moon.
/PARA
A ProgramListing is just like a LiteralLayout, but should
be reserved for listings of programs, which may require
a different style of presentation. ProgramListings
may have LineAnnotations, which are a document author's
comments on the code, not the comments written
into the code itself by the code's author.
A Screen is a representation of all or part of a screen
display, which may be textual or graphical.
A Screen contains text and in-line elements,
in the manner of a LiteralLayout. A Screen has no Title;
if you want
a Screen to have a Title, enclose it in a Figure or Example.
Here's a Screen with text content:
SCREEN ID="SC-1015-12-24"
SYSTEMITEM CLASS="PROMPT"%//SYSTEMITEM> <USERINPUT>make install</USERINPUT
install -c -m 0644 rgb.txt /usr/lib/X11
install -c -m 0644 rgb.dir /usr/lib/X11
install -c -m 0644 rgb.pag /usr/lib/X11
install -c -s showrgb /usr/lib/X11
install in ./rgb done
/SCREEN
If you want to represent a Screen's contents graphically,
use the ScreenShot element. A ScreenShot has a Width
attribute and contains an
optional ScreenInfo and a required Graphic.
The ScreenInfo is a comment about how the image in the
Graphic was created (so you can recreate it if need be),
and is not meant to be displayed or printed; it contains
plain text.
Here's a ScreenShot:
SCREENSHOT
SCREENINFO
Press the F1 key and type “catfile” while holding down the Alt, Page Down, and F12 keys.
/SCREENINFO
GRAPHIC FORMAT="GIF"FILEREF="figs/05.07.gif"
/GRAPHIC
/SCREENSHOT
>
BlockQuotes
BlockQuote is intended for a quotation set off from
the main text, rather than occurring in-line (for an in-line
quote, use Quote).
In a BlockQuote white space is not significant: the lines
wrap. A BlockQuote contains paragraphs and other block-oriented
elements, not plain text.
Sidebars
A Sidebar is a segment of text isolated from the narrative
flow of the main text, typically boxed and allowed to float
in the page layout. Magazines and newspapers contain
many sidebars. A Sidebar may have
a Title and a TitleAbbrev, and must have text in the
form of paragraphs, lists, Figures, or
other block-oriented elements;
no Sects or other Sidebars are allowed.
Footnotes
Within a paragraph or other element, the location of the
footnote mark should be indicated with
FootnoteRef, which points to the
corresponding Footnote with its Linkend attribute,
the value of which is the ID of the associated Footnote.
FootnoteRef may contain plain text, which is the mark to be
displayed, or it may be empty, in which case its Mark
attribute provides
another way of indicating the contents of the mark,
such as an asterisk (*), a number (84), or a dingbat specified by
a name that is to be interpreted by the application
(dagger).
Footnote may occur directly following the FootnoteRef,
or at some other location within the document. It
may contain
paragraph, BlockQuote, InformalEquation, InformalTable,
Graphic, Synopses, LiteralLayout, ProgramListing,
Screen, and any kind of list.
It has ID, Label, Lang, Remap, Role, and XRefLabel
attributes; the ID attribute is required, as
a FootnoteRef must point to it.
Admonitions and Other Blocks
Admonitions are special sections of text that
call attention to some matter of
importance. Admonitions
are one of the following elements:
Caution, Important, Warning, Tip, and Note.
They may have Titles,
paragraphs, and other block-oriented elements,
but no Sects or other admonitions.
Abstract (a document summary) and AuthorBlurb
(author information) may have Titles and paragraphs.
Elements Indicating Nonlinear Relationships
IndexTerms, Links, Anchors, and XRefs all indicate
nonlinear relationships within the text unlike the
hierarchical nesting of
Sects and the linear flow of paragraphs within Sects.
IndexTerms
IndexTerms are words or phrases to be indexed.
The DocBook DTD provides for
three levels of indexing, as well as for “see” and “see
also” indexing. IndexTerms may occur almost anywhere,
but their contents may not do double duty as part
of the text (troff style, not Tex style). The contents
of IndexTerm do not appear in the text itself.
An IndexTerm must contain a Primary, and may contain a
See and one or more SeeAlsos, as well as a Secondary; within
Secondary there may be a See and one or more
SeeAlsos, as well as a Tertiary.
IndexTerm has common, SpanEnd, PageNum, and
Significance attributes.
The SpanEnd attribute is for use in an IndexTerm
ending a span
of text to be indexed; that IndexTerm must be
empty (have no content or end tag) and must have
as the value of SpanEnd the ID of the IndexTerm
that begins the span, earlier in the text.
The PageNum attribute may be used to
indicate the page on which the indexed term is found in
print. Significance may have the value Preferred,
indicating that the entry is the most pertinent of the
series, or Normal (the default).
PARAThis paragraph deals with two subjects that should
be listed in
the index: how to rotate your terminal and how to adjust
its height.
/PARA
INDEXTERM
PRIMARYrotating your terminal
/PRIMARY
/INDEXTERM
INDEXTERM
PRIMARYterminal
/PRIMARY
SECONDARYrotation of
/SECONDARY
/PRIMARY
/INDEXTERM
INDEXTERM
PRIMARYterminal
/PRIMARY
SECONDARYadjustment of
/SECONDARY
SEEALSOtroubleshooting
/SEEALSO
/PRIMARY
/INDEXTERM
IndexEntries
IndexEntries, which occur in the Index,
might be constructed by extracting
and processing the IndexTerms.
IndexEntries themselves
are put together just like IndexTerms, with the
corresponding elements PrimaryIE, SecondaryIE,
TertiaryIE, SeeIE, and SeeAlsoIE.
Links and Anchors
A link is a pointer to another section in the document, or
to another document. The link elements in this revision
are still somewhat provisional, and are under active
review. The most conventional of them
is Link, which may include in-line elements as
text and has a required Linkend attribute, which is the ID
of the element it is linked to. It also has a Type
attribute, so you can assign a role to a Link.
And Link has an Endterm attribute, the value of which
may be the ID of an element whose content
is to appear as the text of the Link.
For example, Link might give the label of a
hot spot explicitly:
To go there, LINK LINKEND="H1-061-ch05-1"
click here
/LINK
or a Link might point to a section and display its title:
Click to go to LINK LINKEND="S1-061-ch05-1"ENDTERM="T1-061-ch05-1"
/LINK
where the content of the element that bears the ID
T1-061-ch05-1 (perhaps the title of Chapter Five)
is displayed as the hot spot. (This is
effectively an unclean form of CONREF.)
Please note that the common attribute XRefLabel
provides another mechanism for displaying text
associated with a Link's target.
Link uses the SGML mechanism of IDREF in pointing to
an element by its ID.
An SGML application may report an IDREF error
when the ID does not occur in the document set being
processed. This may be harmless.
Anchor is an in-line element that marks a location as a
target for a Link (any element bearing an ID
may be a target, of course). Anchor has ID,
PageNum, Remap, Role, and XRefLabel attributes,
but only the ID is required.
It is an empty element: at minimum,
only the start tag is supplied, with an ID:
There is an Anchor <ANCHOR ID="
061-ch05-AN-7"> in this sentence.
>
Two other links are provided in this revision, OLink
(a link that performs some operation on its target)
and ULink (a link that uses a Universal Resource
Locator).
Both of these are experimental and
may be dropped in the future; for details,
see the alphabetical list. In particular,
ULink stores all link information in a format that
SGML does not process, and you cannot expect SGML
browsers to work on ULinks. USE EITHER AT YOUR OWN
RISK.
Cross References (XRefs)
An XRef is a cross reference to another part of a document.
It has Linkend and Endterm attributes, just like Link,
but like Anchor, it may not have content.
XRef must have a Linkend, but the Endterm is optional.
If it is used, the content of the element it points
to is displayed as the text of the cross reference;
if it is absent, the XRefLabel of the cross-referenced
object is displayed.
See
XREF LINKEND="ch05-s1"ENDTERM="ch05-t1",
for more information.
The example above references the section that has the ID
"ch05-s1"and supplies the text of its
Title, which has the ID "ch05-t1", in
the manner of: “See Terminal
Emulation and the xterm Terminal Type>
for more information.”
To include in the cross reference text generated
text that may be associated with the target, e.g.,>
“Figure 5-1.”, use the same mechanism you employ
to generate that text in the first place (your
application's defaults or style sheet).
In-line Elements
In-line elements
are used to label specific terms or usage.
In-line elements may appear anywhere in
a block-oriented element, but may not span two
block-oriented
elements. In documentation these
elements are typically
indicated by font changes.
All of the elements defined in the DTD in the
parameter entities that comprise
inlinechar.gp may appear in-line. (See the
Reference section for brief definitions of in-line elements.)
Using In-line Elements
Trying to determine the most specific in-line element
that can be applied to the specialized terms in your
document can be time-consuming and frustrating. Instead,
you may wish to tag these terms using only the most general
in-line elements. We have found it useful, in
converting files from troff to SGML, to translate the
font changes that mark off these terms in print into
five DocBook tags: Emphasis, Literal, Parameter,
UserInput, and Interface (which correspond
well to our conventional use of
italic, typewriter font, italic typewriter, bold
typewriter, and sans serif; you may wish to choose
other values).
Some such tags (Application, Database,
Interface, MediaLabel, Parameter, Replaceable,
SystemItem, Trademark, and SGMLtag) now have
a Class attribute with delimited values for each
element. This mechanism provides a two-step
approach toward specifying the meanings of
in-line terms. For example, an Interface may
be further specified as Button, Icon, Menu, or
MenuItem through its Class attribute. You can
thus indicate the general meaning of the term
or be more precise, as you like.
Articles
New in this revision is an Article element. A Book may consist
of Articles, in which case it represents an issue of a journal
(and you should provide its ISSN, not ISBN, in the BookInfo)
or a collective work, such as an anthology.
An Article has, in order,
a required ArtHeader, main contents as for Chapter,
then any number of Indexes, Glossaries, Bibliographies,
Appendixes and Acknos, in any order. Article has
common and ParentBook attributes, the latter pointing
to the ID of the enclosing Book. For the details of ArtHeader,
see the alphabetical list of elements.
Reference Entries
A man page or reference page is a distinct form of reference
information. We have modelled our RefEntry element on man
pages. In this DTD, a RefEntry may occur within a
Chapter or Appendix, or
a collection of RefEntries may be made into a book component
called Reference.
RefEntry Basics
A RefEntry contains, in order:
one DocInfo (optional);
one RefMeta (optional);
one or more Comments, links, FootnoteRefs,
or XRefs (optional);
one RefNameDiv (required);
one RefSynopsisDiv (optional);
one or more RefSect1s (required). Schematically,
with additional elements particular to RefEntries:
RefEntry
DocInfo
RefMeta
RefEntryTitle
ManVolNum
RefMiscInfo
RefNameDiv
RefName
RefPurpose
RefSynopsisDiv
Synopsis
RefSect1
RefSect2
RefSect2
RefSect1
RefSect1
RefEntry Variations
Reference entries have conventional divisions, but no single
definitive conventional format.
The arrangement
of information in the initial divisions of a reference entry
may be rather complicated. RefEntry accomodates
several alternate structures for this information.
For example, a typical reference
entry has only a single subject (here, RefName), which is
named in a division that is usually called “Name”
(here, RefNameDiv), and is followed by
an em dash and a short descriptive phrase (here, RefPurpose).
A reference entry for mwm,>
the Motif window manager,
might have this text in its Name division:
"mwm the Motif window manager"
This is simple to tag: “mwm” is a RefName and
the descriptive phrase is a RefPurpose (the em dash should
not be represented in the SGML document).
Other reference entries may provide
a purpose statement on more than one subject
(command, function, file format, and so on).
For example, in a reference entry for grep>
there may be several subjects described by the same purpose
statement:
"grep, egrep, fgrep search a file for a string or regular expression"
Here all the terms in the series are RefNames, and should
be tagged individually.
Still other
reference entries may provide a group name for a series of subjects
that is not itself one of the subjects discussed. For example,
in an AT&T reference entries called “string,” the name of
the reference entry is given in this manner:
"string: strcasecmp, strncasecmp\enspace \enspace
string operators"
In this series, “string,”
is not a function name like the terms that follow the colon
following “string.” In a RefEntry the word “string”
is tagged as a RefDescriptor, which is an optional rather
than a required element of RefNameDiv.
Many of the higher-level elements of RefEntry may occur only
within
RefEntries, not within Chapters or other book components.
These are: RefMeta, RefEntryTitle, ManVolNum, RefMiscInfo,
RefNameDiv, RefDescriptor, RefName, RefPurpose, RefSynopsisDiv, and RefSect1--3.
RefMeta
The RefMeta contains, in order,
a RefEntryTitle, an optional ManVolNum, and any number of
RefMiscInfos.
All this is metainformation, some of which may occur
in the heading of a reference entry. None of it is from the
body of a reference entry.
RefEntryTitle is the primary name by which the
reference entry is sorted and indexed.
ManVolNum is the alphanumerical
designation often supplied in parentheses after the RefEntryTitle,
as in “string(3C).” It refers to the historical arrangement
of reference entries in sections. Other pieces of
information
may follow the ManVolNum,
each
captured with the tag RefMiscInfo, so that you may have a
series of RefMiscInfos (as many as eight have been reported
in legacy documents). For example, O'Reilly's reference entry for
XmuReshapeWidget includes the heading
“Xmu Shape
Extension Utilities,” which should be tagged as a RefMiscInfo.
Other examples of RefMiscInfo contents are copyright,
date, draft status, hardware architecture, and a descriptive
phrase for use in a print header.
Of these RefMeta elements, only RefEntryTitle
may contain in-line elements; the others may
contain only plain text.
Do not be confused by the fact that RefEntryTitle may
contain the same contents
as RefName in the RefNameDiv. For the mwm> reference
entry, “mwm” is the content of both RefEntryTitle and
RefName. This may not always be the case, as in the
“string” example above: in that instance, “string” is
the content of RefEntryTitle, but it is not a RefName.
Remember, the RefMeta does not contain the contents of
the Name division of a reference entry, only metainformation.
REFMETA
REFENTRYTITLEldsysdump
/REFENTRYTITLE
MANVOLNUMldsysdump(1)
/MANVOLNUM
REFMISCINFO CLASS="Sysad"System Administration Commands
/REFMISCINFO
REFMISCINFO CLASS="Copyright"Copyright 1985
/REFMISCINFO
/REFMETA
>
RefNameDiv
RefNameDiv is the top division
of a reference entry, the one usually labelled “Name.”
The RefNameDiv contains, in order, an optional
RefDescriptor (for reference entries such as the “string”
example), one or more RefNames, a required RefPurpose,
followed by any number of RefClasses.
Comments, FootnoteRefs, links, or
XRefs may also appear at the end of RefNameDiv.
In RefClass you indicate the
applicability or scope of the topic of a RefEntry
(such as “LocalBlocking”).
RefName may contain further nested elements
from the parameter entity computerterms.gp, such as
Command or Function.
RefPurpose may contain any in-line elements.
The examples of RefNameDiv cited above are tagged like this:
REFNAMEDIV ID="061-RP72"
REFNAMEmwm
/REFNAME
REFPURPOSE
the Motif window manager
/REFPURPOSE
/REFNAMEDIV
REFNAMEDIV ID="061-RP73"
REFNAME
grep
/REFNAME
REFNAME
egrep
/REFNAME
REFNAME
fgrep
/REFNAME
REFPURPOSE
search a file for a string or regular expression
/REFPURPOSE
/REFNAMEDIV
REFNAMEDIV ID="061-RP74"
REFDESCRIPTOR
string
/REFDESCRIPTOR
REFNAME
strcat
/REFNAME
REFNAME
strdup
/REFNAME
REFNAME
strncat
/REFNAME
REFNAME
strcmp
/REFNAME
REFNAME
strncmp
/REFNAME
REFPURPOSE
string operators
/REFPURPOSE
/REFNAMEDIV
RefSynopsisDiv
RefSynopsisDiv
is intended for the second division of reference
entries, usually titled Synopsis or Syntax. But there
are reference entries without Synopsis or Syntax divisions, so
RefSynopsisDiv
is an optional part of RefEntry. The content of
this division is often simply a
single line giving the syntax for the
subject of the reference entry, or something less
constrained, in some cases including
subheadings.
Thus the content of RefSynopsisDiv may be one or more
synopses
(Synopsis, CmdSynopsis, or FuncSynopsis,
containing a single line or a set of lines), or one
or more synopses
followed by any number of RefSect2s, or one or more RefSect2s.
Here is a valid RefSynopsisDiv:
REFSYNOPSISDIV ID="RS-061-66"
SYNOPSIS
COMMAND>ls</COMMAND
OPTIONAL><PARAMETER>options</PARAMETER></OPTIONAL
REPLACEABLE CLASS="PARAMETER"><FILENAME
directory\_name/FILENAME
/REPLACEABLE
/SYNOPSIS
/REFSYNOPSISDIV
Synopses
In this revision, DocBook has incorporated two new
synopsis types, CmdSynopsis and FuncSynopsis, both
kindly donated by Eve Maler. For explanations of these
elements, please see the alphabetical list of elements.
RefHeads
The rest of a reference entry consists of one or more divisions,
which are to be tagged as RefSect1s, which may have RefSect2s, which may have RefSect3s.
These are just like Sect1--3,
with the same required and allowable contents.
Miscellaneous
Some elements are not part of the
illustrations or body
of text in a printed work. Such elements
may appear in a printed work
but are not
part of the text. Others are provided in case they
should be needed for some aspect of on-screen display or book
production (TitleAbbrevs). Still others are
metainformation, such as comments.
TitleAbbrev may be provided where a long
Title might be inappropriately truncated in some
on-line display such as a title bar, or for use in a printed
header
or footer.
RevHistory, an element of DocInfo, records the authorship of
changes to
a book. It consists of one or more Revisions, each of which
must contain a RevNumber, a Date, one or more AuthorInitials, and
a RevRemark.
A Comment, containing in-line elements and plain text,
is something not meant to be displayed
or printed, such as a message to a production editor.
Beware! Comment is not an SGML comment, it is an
element. Just tagging text as a Comment will not ensure
that it is hidden; you must arrange that in your
application. And in line-specific elements you may find
that the line breaks in your comment are rendered by
your application.
The Elements Alphabetized
Emphasized entries indicate
block-oriented elements.
“Dropped” elements appeared in version 1.2.2 but do not
appear in the current version; many have been shifted
to attribute values in cptrphrase.gp.
Common Attributes
Common attributes now include ID, Lang (language), Remap
(to store the former GI of an element in a document filtered
to Docbook), Role (to type Docbook elements when
need be), and XRefLabel (text to be displayed as the
label of cross references to a block-oriented element).
ID is an identifier, which must be a
string that is unique at least within the document and
which must begin with a letter. Lang should be a
language code drawn from ISO 639 (perhaps extended with
a country code drawn from ISO 3166, as en_US). Use
it when you need to signal your application to change
hyphenation and other display characteristics.
Remap is a device for
preserving a previous tag name when fitting a document
to the DocBook DTD.
Think of CHAPTER Remap=“Fascicle”
as saying, “I'm a Chapter now, but in a previous life
I was a Fascicle.” Role allows you to clone DocBook
elements without creating new ones: if you have lists
of vegetables and lists of fruit (perhaps displayed
differently), give them
Role=vegetables and Role=fruit attributes.
Other Attributes
Certain other attributes occur regularly. PageNum is
the number of the page on which a given element begins
or occurs in a printed book. Label holds some text
associated with its element that is to be output when
the document is rendered. XRefLabel holds some text
that is to be used when a cross reference (XRef)
is made to its element. Type is used with links,
as it is clear that different types of links may be
required; it duplicates the function of Role.
The Class attribute has been introduced in an attempt to
control the number of computer-specific in-line elements.
The elements that bear the Class attribute, such as
Interface, have general
meanings that can be made more specific
by providing a value for Class from the delimited list
for that element. For example, for the Interface element
one may specify Menu, or Button; for the MediaLabel
element one may specify CDRom or Tape. Each element
has its own list of permissible values for Class, and
no default is set, so you can ignore this attribute
if you wish.
Some attributes are defined with the keyword %yesorno;,
which resolves to NUMBER. To supply the required number,
which must be either 1 or 0, you can use the
parameter entities %yes; (1); or %no; (0).
An attributes that has the keyword IMPLIED bears no
processing expections if it is absent or its
value is null. Application designers might wish to
supply plausible defaults, but none is specified here.
However, it would be plausible to imply that the
language of a DocBook instance is U.S. English
unless specified otherwise. (This matter may be clarified
when character set specification is added to the DTD;
for now, the character set must be inferred from the
Lang attribute value, if present.)
cptrphrase.gp
This parameter entity has been introduced to provide
some structure for in-line elements related to computers.
Its contents are: plain text,
Anchor, BeginPage, all the index
terms, Comment, Subscript, Superscript,
all the kinds of links, Action, Application, ClassName,
Command,
ComputerOutput,
Database, ErrorName, ErrorType,
EventStructure, EventType,
Filename, Function, Hardware, Interface,
InterfaceDefinition, KeyCap, KeyCode, KeySym, LineAnnotation,
Literal, Mask, MediaLabel, MsgText, Option,
Optional, Parameter, Property, ProtocolRequest,
Replaceable, ReturnValue, StructField, StructName, Symbol,
SystemDialog, SystemItem, Token, Type, and UserInput.
Many of these elements now have attributes
with delimited value lists; some former in-line elements now appear as
values for those attributes.
“In-line” vs. “In flow”
In this document, “in-line” means ”occuring within a line
of text, like a character or character string, not causing
a line break.” This term is sometimes used to
refer to objects such as an illustration around which
something like a paragraph is wrapped; here that circumstance
will be called “in flow.” There is no provision yet
for indicating that an object is in flow, but one could
make creative use of the Role attribute to do so.
A related point: formal objects have titles; informal
objects do not. That an object is informal does not mean
that it is in-line: these are two different
characteristics.
CALS Tables
In this revision, the former Table models have been
replaced by one derived from MIL-M-28001B, dated
26 July 1993 (supersedes MIL-M-28001A of 20 July
1990.)
The documentation of Table and its subelements,
below, has been taken from that document,
with some editing and attempts at clarification.
List of Elements
Abstract
A document summary.
Abstract contains an optional Title followed by
paragraphs, and
has common attributes.
Abbrev
An abbreviation, especially one
followed by a period. It contains plain text and
has common attributes.
Ackno
Acknowledgements in an Article.
It contains plain text.
Acronym
A pronounceable contraction of
initials, usually printed in all caps or small caps.
It contains plain text and
has common attributes.
Action
A function invoked in response to a user event. It may contain members of cptrphrase.gp,
and has common and MoreInfo attributes.
For the MoreInfo
attribute see Application.
Address
A real-world address. It contains
any number, in any order, of: Street, POB, Postcode,
City, State, Country, Phone, Fax, and Email.
Affiliation
Author's institutional affiliation.
It contains, in order, an optional ShortAffil, any number
of JobTitles, optional OrgName, any number of
Orgdivs, and any number of Addresses.
Anchor
Marks a target for a Link.
Anchor may appear almost anywhere, and has no content.
Anchor has ID, Pagenum, Remap, Role, and XRefLabel attributes;
the ID is required.
Appendix
May occur only after Chapters
or References, in a Book.
Appendix begins with an optional DocInfo, followed by
a required Title, optional TitleAbbrev, and anything
found in the body of a Chapter.
It has common and Label attributes.
Application
The name of a software program.
It may contain members of cptrphrase.gp,
and has common, Class, and MoreInfo attributes.
Class may be Hardware or Software (no default). MoreInfo
may have the value RefEntry, indicating that a
RefEntry exists containing additional information
about this term. The default value for MoreInfo is None.
Arg
Argument in a CmdSynopsis. Arg may contain
any number of Args, Groups, Options, SynopFragmentRefs, Replaceables,
in any order, mixed with plain text. Arg is defined in
the DTD as having common attributes and the attributes
defined by the parameter entities argchcatt and repatt.
argchcatt or “argument choice attribute”
resolves to the attribute
Choice, with allowed values Opt (the Arg is
optional; the default), Req (it is required),
and Plain (neither optional nor required).
repatt or “repetition attribute”
resolves to the attribute Rep, with allowed
values Repeat (the Arg may be repeated; the default)
and Norepeat (the Arg does not repeat).
ArtHeader
Metainformation for an Article.
ArtHeader has, in order, a required Title, optional
TitleAbbrev, optional Subtitle, one or more AuthorGroups,
optional BookBiblio, a required ArtPageNums,
any number of
Abstracts, any number of ConfGroups, and finally any number
ContractNums and ContractSponsors, in any order.
ArtHeader has common attributes.
Article
An article in a journal. Book may
be used to hold Articles. An Article has, in order,
a required ArtHeader, main contents as for Chapter,
then any number of Indexes, Glossaries, Bibliographies,
Appendixes and Acknos, in any order. Article has
common and ParentBook attributes, the latter pointing
to the ID of the enclosing Book.
ArtPageNums
Page numbers of an Article
as published. It contains plain text (e.g., 23-147).
Author
Author of a document, occuring in
AuthorGroup. It consists of
one or more of the following, in any order:
Honorific, Firstname, Surname, Lineage, OtherName,
Affiliation, and AuthorBlurb. It has common
attributes.
AuthorBlurb
Short description of
author.
AuthorBlurb contains an optional Title followed by
paragraphs, and
has common attributes.
AuthorGroup
Wrapper for Author information.
It contains one or more CorpAuthors, Collabs, and
Authors, in any order.
AuthorInitials
Indicates the author of
a Revision or Comment. It contains plain text
and has common attributes.
BeginPage
Marks a page break in a print
version of a work that may be displayed online.
It is without content, but has ID, PageNum, Remap, Role, and
XRefLabel attributes. The ID is required.
The value of PageNum, which is
not required, should be
the folio (page number) of the page beginning at that
point. Usage Note: Once you give
a PageNum to a BeginPage, subsequent BeginPages should
be assumed to indicate that value incremented by one per
BeginPage. You can indicate a change or reset in page
numbering by providing a PageNum value for a later
BeginPage.
BiblioDiv
A section of a
Bibliography. It may have, in order, an
optional Title, optional TitleAbbrev,
any number of block-oriented elements,
followed by one or more BiblioEntries.
It has common attributes.
BiblioEntry
An entry in a Bibliography.
It may begin and end with BiblioMiscs,
between which must be an ArtHeader, BookBiblio,
or SeriesInfo. That is, the main content of a
BiblioEntry may be identical to a section of
metainformation. BiblioEntry has common attributes.
Bibliography
A bibliography. It may be a
book component on its own, or may appear within a Preface, Chapter, or Appendix, or at
the end of a Glossary. It may have a DocInfo,
a Title and a TitleAbbrev, then optional
block-oriented elements, and then
one or more BiblioEntries or one or more BiblioDivs.
It has common attributes.
BiblioMisc
Untyped information required in a
BiblioEntry or BookInfo, in addition to the elements
required there. It contains plain text and
has common attributes.
BlockQuote
A quotation set off from the main text,
rather than occurring in-line. It may have a Title, followed
by block-oriented elements. It has common attributes.
Book
A collection of book components.
The Book content model has been drawn
more tightly since version 1.2.2, but is loose enough
to accomodate English, French, and Japanese books.
A Book may have
a Title and TitleAbbrev, followed in order by an optional
BookInfo, an optional ToC,
any number of LoTs, any number of Prefaces,
main contents, and back matter. The main contents are
required, and must be one or more Parts;
one or more Chapters followed by any
number of References;
one or more Articles; or one or more References.
All back matter is optional, but must appear in order:
any number of Appendices,
a Glossary, a Bibliography, and any number of Indexes
and SetIndexes,
followed by any number of LoTs followed by an optional
ToC. Book has common, FPI, and Label
attributes. The FPI attribute is intended to hold an
SGML Formal Public Identifier for the Book;
the Label attribute can be used to supply the
number of a Book, or you can use the content of the VolumeNum element in BookInfo.
in constructing Formal Public Identifiers you use
your ISBN publisher's prefix. In the ISBN
1–565692–043–0, for example, the publisher's
prefix is 565692.
BookAcronym
Dropped.
BookBiblio
All the information about a book
that may be relevant
to a bibliographical citation; occurs in BookInfo and
may be used in BiblioEntry.
Only Title and AuthorGroup
are required. BookBiblio may contain, in order:
the required Title, optional TitleAbbrev,
Subtitle, and Edition, followed one or more required
AuthorGroups; then, optionally, either an ISBN followed
by an
optional VolumeNum or an ISSN followed by
optional VolumeNum, optional IssueNum, and an
optional PageNums. After these elements there may
occur, again optionally and in order,
InvPartNumber, ProductNumber, ProductName,
PubsNumber, and ReleaseInfo; then there may be any number
of Pubdates followed by any number of Publishers,
followed by optional
Copyright, then optional SeriesInfo; then any number of
Abstracts, any number of ConfGroups, any number
of ContractNums mixed with any number of ContractSponsors,
and an optional
PrintHistory followed by an optional RevHistory.
BookBiblio has common attributes.
is the numbers of the pages contained in a given issue
or volume
BookInfo
Metainformation for a Book,
in which it may appear. BookInfo must contain
a BookBiblio, followed by any number of LegalNotices,
followed by any number of ModeSpecs (which
are pointed to by the LinkMode attribute of OLink,
and are collected here for convenience).
BookInfo has common attributes
and a Contents attribute, the
values of which are the IDs of the ToC, LoTs,
Prefaces, Parts, Chapters, Appendixes, References,
Glossary, Bibliography, and indexes
comprising the Book, in the order of their appearance.
BookTitle
Dropped.
BridgeHead
A free-floating heading not
tied to the Sect hierarchy. It may contain
in-line elements and has common and Renderas
attributes. Use the Renderas attribute to indicate
the format in which the BridgeHead should appear (Sect1,
Sect2, Sect3, Sect4, Sect5, or Other, the default).
Button
Dropped. See Interface.
Caution
An admonition set off from the text;
Tip, Warning, Important, and Note all share its model.
Its contents may include paragraphs, lists, and so forth,
but not another admonition.
Caution and its sisters have common attributes.
Chapter
A part of a Book.
Chapter contain anything except
higher-level elements
such as Part, Book, and Set, or peers such as
Appendix and Preface. A Chapter
may begin with a DocInfo, followed by
a required Title, optional TitleAbbrev, and body.
The body may be
either paragraphs and block-oriented elements or Sects containing
them. At the beginning and end of the body of
a Chapter, or the beginning and end of any Sect,
there may be any number of ToCs, LoTs, Indexes, Glossaries,
and Bibliographies, not that such an organization is
recommended for ordinary use.
Chapter has common and Label attributes.
Character
An element of a writing
system. Characters may belong to Charsets, and in some contexts
fonts represent characters.
(See Glyph, Font.) It contains plain text and
has common attributes.
Charset
A conventionally defined
set of characters, (not a font).
It contains plain text and
has common attributes.
Citation
Any in-line bibliographic
reference to another published work that uses a reference
string, such as an abbreviation in a Bibliography.
Compare CiteTitle.
Citation contains plain text and
has common attributes.
CiteBook
Dropped. See CiteTitle.
CiteChap
Dropped. See CiteTitle.
CiteSect
Dropped. See CiteTitle.
CiteTitle
A citation for some published
work. Compare Citation.
It may contain members of cptrphrase.gp,
and has common and Pubwork attributes.
The value of Pubwork should indicate the type
of work cited; it may be Article, Book, Chapter,
RefEntry, or Section (no default).
CiteRefEntry
A citation of a reference
entry. It must have a RefEntryTitle, followed
by an optional ManVolNum. It has common attributes.
City
Part of Address. It contains plain text.
Classname
The name of the class to which a
program component belongs.
It contains plain text and
has common attributes.
CmdSynopsis
Synopsis for a Command. A
CmdSynopsis contains any number of
Args and Groups, in any order, followed by a
single required
Command, another set of any number of Args and
Groups, in any order, and ending with any number of
optional SynopFragments. CmdSynopsis has common,
Label, and Sepchar attributes. Label has no
default; Sepchar has the default “ ”.
The following is courtesy Eve Maler (see also
the entries for the subelements elsewhere in
this list:
An argument at the command level (Arg)
is a parameter passed to a
command to specify or modify the command's behavior; it
often consists of a variable value
(Replaceable)
such as a filename field, or an option
(Option) and its own nested
argument (Arg). If the contents of an
argument are not marked up further, they are assumed to be
something the user must type as shown (probably an option,
but this is implicit). The Choice attribute on the two
argument elements indicates whether the argument must be
present (“Req”, the default), whether it
is optional (“Opt”), or whether no indication of presence
is given (“Plain”, the default).
A group (Group) as a peer
or child of an argument is a
collection of arguments, options, or other constructs that must appear in some
relation to each other. For example, three options that are
exclusive of each other and are optional would be in a group
with a choice of “Opt” (the default).
The “Optmult” choice allows zero or more of the
children of the group to be supplied, and the “Reqmult”
choice requires one or more of the children of the group to
be supplied.
An option (Option) is a literal string or name of a
parameter-keyword controlling the behavior of the command; a
variable value (Replaceable) is a
mnemonic name for a value that the user must supply, such as
an input file name. The Option and Replaceable
elements are available in text as
well as in synopses. Stacks of options (for example,
“-aefstuv”) should
be put into a single Option element for simplicity.
Depressingly complex constructs may
appear anywhere within a
synopsis. A SynopFragment reference (SynopFragmentRef) is a
special kind of variable value assigned in place of this
construct, which is
then broken out into its own synopsis subset (SynopFragment) for
clarity. A SynopFragment must have an ID, and any
SynopFragmentRefs supplied
must point to some SynopFragment.
Plain text within a CmdSynopsis
is allowed only inside Cmd, Arg,
Option, Replaceable, and SynopFragmentRef. The
top-level separator character attribute
value (“ ” by default) should
be used to separate arguments and groups
from their repeat indicators (“. . .”) and
to separate Commands and their arguments and groups at the top level.
The CmdSynopsis structure does
not meet the needs of DCL
and other VMS-related command languages that have command
parameters such
as /[NO]WRITE, positional versus nonpositional parameters, and so on.
Probably additional low-level elements would have to be
added to the mix and the top-level structure enhanced
slightly to account for
these. However, CmdSynopsis
appears to meet most UNIX-related needs.
Processing expectations:
The “Opt” settings on arguments and groups (and probably
“Optmult” as
well for now) should produce square brackets.
The “Req”
settings (and probably “Reqmult” as well for now)
should produce curly braces. The children of Group (if
there is more than one child) should be either separated by vertical bars or formatted as a stacked list.
Spacing at the Command and Group levels
is controlled by formatter defaults and/or the
sepchar setting.
Example command synopsis in typical UNIX(tm) format:
rm [-f] [-r] [-i] [-] {filename|dirname} . . .
| | | | | | | | |
| optional args | | | repeat indicator
| (contain options)| | |
| | | second child of group
command name | |
| first child of group
|
required repeatable group
SGML source for this example:
CMDSYNOPSIS
COMMANDrm/COMMAND
ARG Choice="opt"-f/ARG (OPTION not required for arg contents
ARG Choice="opt"-r/ARG unless doing extra-special processing)
ARG Choice="opt"-i/ARG
ARG Choice="opt"-/ARG (various synopsis formats
GROUP Choice="req" Rep="repeat" can be generated)
REPLACEABLEfilename/REPLACEABLE
REPLACEABLEdirname/REPLACEABLE
/GROUP
/CMDSYNOPSIS
Collab
A collaborative group
of authors. It contains a required CollabName
followed by any number of Affiliations.
CollabName
Name of a collaborative group
of authors. It contains plain text.
ColSpec
Column specifier,
that is, formatting information for a
column in a Table, part of TGroup, THead, or TGroup.
ColSpec is an empty element, bearing common
and Align, Char, Charoff,
Colname, Colnum, Colsep, Colwidth, and Rowsep
attributes. The default values come from the TGroup,
THead, or TFoot that starts the current enclosing group.
Each ColSpec is for a single column, so it properly has a
column number, Colnum, implicitly in order starting
from 1, and an optional Colname by which it is known when
used in any SpanSpec or in Entry.
A ColSpec set on THead or TFoot should be complete for
all columns. It overrides those on the containing TGroup
and applies to just the THead or
TFoot. If there is no ColSpec used within THead or
TFoot, then the ColSpec of the containing TGroup (or the
prior TGroup) is used. ColSpecs from the containing
TGroup apply to TBody.
For TGroupStyle, see TGroup.
Align controls the horizontal position
of text within the column.
The value of Align may be Left (quad flush left),
Center (centered), Right (quad flush right),
Justify (both quad left and right), or Char (align to
the left of Char, positioned by Charoff). There is
no default.
Char contributes to Align. If the
value of Align is “char”, the value of Char
should be a character on the first occurrance
of which the entry is to be aligned. If that
character does not occur in the entry, the entry
is aligned to the left of the position determined
by Charoff. (Think of using the decimal point to
align decimal numbers: Char=“. ”and
Charoff says how far over in the column the decimals
should be; if no decimal occurs, the number is an
integer and is aligned to the left of the decimals.)
No value implies there
is no character to align on.
The default is implied, from the enclosing TGroup.
(That is, you normally declare that an entire TGroup
shall be decimal-aligned, but if you need to align
a specific column differently, you can do it by
specifying another Char at the ColSpec level.)
Charoff contributes with Char to Align.
Charoff is the proportion
of the current column width, expressed in percentage,
to be allowed before the left edge of the first occurrence
of the character given as the value of Char.
The default is inherited from the enclosing TGroup.
That is, if columns in a TGroup are to be decimal-aligned,
and the decimal point is to fall three-quarters of the
way across each cell (most of your numbers are of the
form 123.4), you could set Charoff to 75 in
TGroup; that value would be inherited by ColSpec, where
you could modify it for a specific column (for
example, by setting it to
50 for a column of numbers of the form 12.34).
Colname gives the name of the column, which
is used
to specify the position in a row, or the start or end of a
horizontal span of columns (SpanSpec). There is no default.
Colnum gives the number of the column,
counting from 1 at left of the table.
There is no default.
Colsep
determines column separators. If its value
is Yes, display the internal column rulings to
the right of each item; if No, do not
display it. It is ignored for the last column, where the
Frame setting applies. There is no default. The
value is inherited from TGroupStyle if used.
Colwidth is either a proportional
measure of the form number*, such as “5*” for
5 times the proportion, or “*” (=“1*”); or a
fixed measure, such as 2pt for 2
points, 3pc for 3 picas; or a mixed measure, such as 2*+3pt.
Coefficients are positive numbers with up to
two decimal places. There is no default.
If no value is given, the value should
be obtained from the FOSI, or, if there is no FOSI value,
the value 1 should be used. (Perhaps this means that
you can vary the width of columns by stating their relative
proportions, or you can give fixed widths. If you use
a decimal number less than one, express it in the form
0.2, not .2.)
Rowsep
determines row separators. If its content is
Yes, display the internal vertical row ruling
below each item; if No, do not display it. It is
ignored for the last row of the table, where
the value of Frame applies to the entire Table.
There is no default.
The value is inherited from TGroupStyle, if used.
Command
An executable program, or
the entry a user makes to execute a command.
It may contain members of cptrphrase.gp,
and has common and MoreInfo attributes.
For the MoreInfo
attribute see Application.
Comment
A remark made within the document file that
is intended for use during interim stages of production.
A Comment should not be displayed to the reader of the
finished, published work. It may appear almost anywhere,
and may contain almost anything
below the Section level. Note that,
unlike an SGML comment, unless you take steps
to suppress it, the Comment element
will be output by an SGML parser
or application. You may wish to do this to display Comments
along with text during the editorial process.
ComputerOutput
Data presented to the user by
a computer.
It may contain elements from cptrphrase.gp,
and has common and
MoreInfo attributes For the MoreInfo attribute
see Application.
ConfGroup
A wrapper for information about
a conference. It contains any number of ConfDates,
ConfTitles, ConfNums, Addresses, and ConfSponsors,
in any order.
ConfNum
The number of a conference. It
contains plain text.
ConfSponsor
Sponsor of a conference in connection
with which a document was written. It contains plain text.
ConfDates
Dates of a conference in connection
with which a document was written. It contains plain text
(e.g., 21-24 May 1927).
ConfTitle
Title of a conference in connection
with which a document was written. It contains plain text.
Constant
Dropped. See SystemItem.
ContractNum
Number of a contract under which
a document was written. It contains plain text.
ContractSponsor
Sponsor of a contract under which
a document was written. It contains plain text.
Copyright
Copyright information about
a document. It consists of one or
more Years followed by any number of Holders.
CorpAuthor
Corporate author of a book, for use
in BookInfo or BiblioEntry. It contains plain text
and has common attributes.
CorpName
Name of a corporation. It contains
plain text.
Country
Part of Address. It contains plain text.
Data
Optional component of FuncParam and
ParamDef. It wraps plain text, Replaceable, more Data,
Emphasis, and may contain links and indexing information.
It has common attributes.
Date
Date of publication or revision.
It contains plain text. (No provision
has been made for representing eras; you could include this
information along with the date data.)
Database
An organized set of data.
It may contain members of cptrphrase.gp,
and has common, Class, and MoreInfo attributes.
Class may have the value
Name, Table, Field, Key1, Key2, or Record
(no default). For the MoreInfo
attribute see Application.
DbField
Dropped. See Database.
DbName
Dropped. See Database.
DbRecord
Dropped. See Database.
DbTable
Dropped. See Database.
DocBook
Dropped. Use the book component's
name
(e.g., Chapter) as the Doctype, or construct
a shell Book in which you can insert individual
book components as entities.
DocInfo
Metainformation for a book
component, in which it may appear. Only Title and AuthorGroup
are required. DocInfo may contain, in order:
the required Title, optional TitleAbbrev and
Subtitle, followed by one or more
AuthorGroups, any number of
Abstracts, an optional RevHistory, and any number of
LegalNotices.
DocInfo has common attributes.
Edition
The edition of a document. It contains
plain text.
Editor
The editor of a document.
Contents are the same as for Author.
Email
Part of Address. It contains plain text.
Emphasis
Provided for use where you would
traditionally use italics
or bold type to emphasize a word or phrase.
It contains plain text and
has common attributes.
Entry
A euphemism for a cell in a table—you'd
rather be in an Entry than in a Cell, wouldn't you?
An Entry occurs in
a Row, and must have either some assortment
of paragraphs, admonitions, lists,
and Graphics, or in-line elements.
Entry has common
and Align, Char, Charoff, Colname, Colsep,
Morerows, Nameend, Namest,
Rotate, Rowsep, Spanname, and VAlign attributes.
Attribute values may be inherited
from enclosing elements that share the same
attribute.
“An Entry not specified by a SpanSpec gets its
defaults from its starting column.”
Align controls the horizontal position
of text within the column.
The value of Align may be Left (quad flush left),
Center (centered), Right (quad flush right),
Justify (both quad left and right), or Char (align on
leftmost of Char, positioned by Charoff). There is
no default; the value may be inherited from
ColSpec or SpanSpec.
Char contributes to Align. If the
value of Align is “char”, the value of Char
should be a character on the first occurrance
of which the entry is to be aligned. If that
character does not occur in the entry, the entry
is aligned to the left (the original doc incorrectly
specifies “right”)
of the position determined
by Charoff.
The default is inherited; no value implies there
is no character to align on.
Charoff contributes with Char to Align.
Charoff is the proportion
of the current column width, expressed in percentage,
to be allowed before the left edge of the first occurrence
of the character given as the value of Char, if any.
The default is inherited from ColSpec or SpanSpec.
Colname gives the name of the column,
which is used
to specify the position in a row, or the start or end of a
horizontal span of columns (SpanSpec). There is no default;
omit if SpanName is present. The implied value is either
the first column of the Row, or, if already in a Row,
the next column after the end of the prior Entry or
EntryTbl.
Colsep determines column separators.
If its value
is Yes, display the internal column rulings to
the right of each Entry; if No, do not
display it. It is ignored for the last column, where the
Frame setting applies. (In CALS,
Yes is expressed as 1 and No as 0.)
There is no default; if no value is given the
value is inherited from ColSpec or SpanSpec.
Morerows is the number of
additional rows in a
vertical straddle. The default is 0.
Nameend is the name of the rightmost
column of a span. Names are identified in the
ColSpec of the current TGroup. There is no default.
Namest or Name Start,
is the name of the leftmost column
of a span. Names are identified in the
ColSpec of the current TGroup.
Rotate
governs rotations, which are not additive to
those specified in the FOSI.
Values may be Yes or No (1 or 0).
No specifies no rotation; Yes specifies
90 degrees rotation counterclockwise
to table orientation. No other values are
supported!
Rowsep
determines row separators. If its content is
Yes, display the internal vertical row ruling
below each item; if No, do not display it. It is
ignored for the last row of the table, where
the frame value applies. There is no default.
The value is inherited from Row, if used there.
Spanname is the name of a horizontal span.
No default.
VAlign governs the vertical
positioning of text within an Entry.
Allowed values are Top, Middle, and Bottom
(no default).
EntryTbl
A form of subtable. It
may occur in Row, along with Entry.
Several EntryTbls of differing formats
may occur in the same Row of a
TBody, but EntryTbl may not contain itself. Aside
from that restriction, EntryTbl contains one or
more sets of these elements, in order:
any number of ColSpecs, any number of SpanSpecs,
an optional THead, and a required TBody.
There is no implication
of alignment of subrows in different EntryTbls.
Default attribute values come instead from those
of like-named attributes on enclosing
elements: Table, TGroup,
ColSpec, SpanSpec, THead, TFoot, TBody, or
Row. EntryTbl has common, Align,
Char, Charoff, ColName, Cols, Colsep, Nameend, Namest,
Rowsep, Spanname, and TGroupStyle attributes.
Align controls the horizontal position
of text within the column.
The value of Align may be Left (quad flush left),
Center (centered), Right (quad flush right),
Justify (both quad left and right), or Char (align to
the
left of Char, positioned by Charoff). There is
no default; the value may be inherited from ColSpec
or SpanSpec.
Char contributes to Align. If the
value of Align is “char”, the value of Char
should be a character on the first occurrance
of which the entry is to be aligned. If that
character does not occur in the entry, the entry
is aligned to the left (the original doc incorrectly
specifies “right”) of the position determined
by Charoff. There is no default.
Charoff contributes with Char to Align.
Charoff is the proportion
of the current column width, expressed in percentage,
to be allowed before the left edge of the first occurrence
of the character given as the value of Char, if any.
The default is inherited from the enclosing TGroup.
Colname gives the name of the
leftmost column of EntryTbl. There is no default.
Cols is the number of columns in the
EntryTbl. There is no default.
Colsep
determines column separators. If its value
is Yes, display the internal column rulings to
the right of the EntryTbl,
except if the EntryTbl falls in the the last column, where the siderule (sic)
setting applies; if No, do not display it.
There is no default. The
value is inherited from the enclosing TGroup.
Nameend is the name of the rightmost
column of a span. Names are identified in the
ColSpec of the current TGroup. There is no default.
Namest or Name Start,
is the name of the leftmost column
of a span. Names are identified in the
ColSpec of the current TGroup. There is no default.
Rowsep
determines row separators. If its content is
Yes, display the internal vertical row ruling
below the EntryTbl; if No, do not display it. It is
ignored for the last row of the table, where
the frame value applies. There is no default.
The value is inherited from the enclosing
TGroup.
Spanname is the name of a horizontal span.
TGroupStyle is the name of
a table group style
defined in the FOSI. There is no default.
Epigraph
A brief section of poetry or prose
at the start of a chapter. It contains paragraphs and has common attributes.
Equation
A titled mathematical equation displayed
on a line by itself, rather than in-line. It has an optional
Title and TitleAbbrev, followed by either
an InformalEquation or a Graphic (see Graphic).
Equation has common and Label attributes.
ErrorName
An error message reported by a computer.
It contains plain text and has common attributes.
ErrorType
A classification of an error message
reported by a computer.
It contains plain text and has common attributes.
EventStructure
The code that defines an Event.
It contains plain text and
has common attributes.
EventType
A classification of an event.
It contains plain text and
has common attributes.
Example
Intended for sections of program source code
that are provided as examples in the text.
It contains a required Title and an
optional TitleAbbrev, followed by one or more block-oriented
elements in any combination. It has common and Label
attributes. A simple Example might contain a Title
and a ProgramListing.
ExternalLink
Dropped.
Fax
Part of Address. It contains plain text.
Figure
An illustration.
It must have a Title, and may have a
TitleAbbrev, followed by one or more of
BlockQuote,
InformalEquation, Graphic,
InformalTable, Link, LiteralLayout,
OLink, ProgramListing, Screen, Synopsis, and ULink,
in any order. Figure has common,
Label, and Float attributes; Float indicates
whether the Figure is supposed to be rendered
where convenient (yes) or at
the place it occurs in the text (no, the default). To
reference an external file containing graphical
content use the Graphic element within Figure.
Filename
The
name of a file, including pathname if this
information is present. It may contain members of cptrphrase.gp,
and has common and MoreInfo attributes.
For the MoreInfo
attribute see Application.
FirstName
(Western-style) given name
of Author,
Editor, or OtherCredit. It contains
plain text.
FirstTerm
First occurrence
of a word in a given context.
It contains plain text and
has common attributes.
Font
A collection of Glyphs (see Glyph).
It contains plain text and has common attributes.
Footnote
The contents of a footnote, when
the note occurs outside the block-oriented element in
which the FootnoteRef occurs.
(Compare InlineNote.)
The point in the text where the mark for a specific
footnote goes is indicated by FootnoteRef.
Footnote may contain Para, SimPara, BlockQuote, InformalEquation, InformalTable,
Graphic, Synopsis, LiteralLayout, ProgramListing,
Screen, and any kind of list.
It has ID, Label, Lang, Remap, Role, and XRefLabel
attributes; the ID attribute is required, as
a FootnoteRef must point to it.
FootnoteRef
Identifies the location for a footnote mark.
It may contain plain text, which is the mark to be displayed, or it may be empty, in which case the Mark
attribute provides
another way of indicating the contents of the mark (such as
an asterisk, *, a number, 84, or a dingbat specified by
a name that is to be interpreted by the application).
FootnoteRef has ID, Linkend, and Mark
attributes. The Linkend attribute,
which is required, has as its value the ID of
the associated Footnote, and the Mark.
ForeignPhrase
Any word or words
from a language other than
that of the document which you want to mark off
in some way. In English, inter alia and
c'est la vie are ForeignPhrases.
It contains plain text and has common attributes.
FormalPara
A paragraph with a Title.
FormalPara contains a required Title followed
by a required Para, and has common attributes.
FuncDef
Part of a FuncSynopsis.
Like Paramdef, it provides
data type information and the name of the
Function (or Parameter, in the case of ParamDef)
this information applies
to. A FuncDef may contain any combination of
plain text, Replaceable, Data, or Function, in any order.
It has common attributes.
Separating this information from the rest of
the synopsis avoids messing with data type
information that appears before or after
the item it applies to, such as array
information (“[]”). It also avoids the issue of
placing the pointer (“*”) indicator (next to the rest of
the left-hand data type or next to the Parameter or Function
name?). Any spaces that surround the
Parameter or Function must be inserted by the writer.
FuncParams
Optional component of ParamDef.
It supplies “inner parameters” for Paramters that
are pointers to Functions. FuncParams
contains elements from ctprphrase.gp and has
common attributes.
FuncSynopsis
(contributed Eve Maler, along
with remarks on its subelements.)
A C synopsis that shows a prototype or
definition indicating a function's name. A FuncSynopsis
also indicates the data type of its return value, and
the positions, purposes, and data types of its
parameters. A FuncSynopsis begins with an
optional FuncSynopsisInfo, which contains additional
information about the synopsis that follows; line breaks
and leading white space are significant within a
FuncSynopsisInfo. This is followed by
one or more blocks defining a function (you might
use more than one for connecting related sets of functions).
Each of these blocks consists of a required FuncDef,
followed by a Void, a VarArgs, or one or more ParamDefs.
Void, Varargs, and and ParamDef
are mutually exclusive. Usage Note:
You should supply no specific information on the arguments before the ellipsis that VarArgs should output when
rendered, but if it is necessary
to represent the ellipsis in the source it may
ben enclosed within a final ParamDef.
FuncSynopsis has common and Label attributes.
The processing application is expected to
provide all parentheses, semicolons, and the like. The
exceptions are any spaces surrounding function and parameter
names, any parentheses or commas or spacing
inside lists of data types of parameters that are pointers
to functions, and the parentheses around those parameter
names themselves. These exceptions are a bit confusing in
the unusual case (pointers to functions), but they
greatly simplify tagging and still
allow either K&R style or ANSI C style to be produced
(assuming writers have cooperated in supplying enough
information for ANSI).
FuncSynopsisInfo
Information supplementing
the FuncDefs of a FuncSynopsis. It contains elements
of ctprphrase.gp, and within it line breaks
and leading white space are significant.
See FuncSynopsis. It has common attributes.
Function
A subroutine in a program or external
library. It may contain members of cptrphrase.gp,
and has common and MoreInfo attributes.
For the MoreInfo
attribute see Application.
FunctionParam
Dropped.
See Parameter.
Glossary
A glossary of terms. Glossary
may occur within a Chapter, Appendix, or Preface,
or may be a book component in its own right.
It contains in order an optional DocInfo, optional
Title, and optional TitleAbbrev, followed by
any number of
block-oriented elements, followed by
one or more GlossEntries or one or more GlossDivs.
It has common attributes.
GlossDef
The definition attached to a GlossTerm
in a GlossEntry. It may
contain Comments, GlossSeeAlsos,
paragraphs, and other block-oriented
elements, in
any order; it has common and Subject attributes. The Subject
attribute may hold a list of subject areas (e.g., DCE RPC
General) as keywords.
GlossDiv
A division of a Glossary.
It may have a Title and TitleAbbrev, followed by
block-oriented elements, followed by
one or more GlossEntries. It has common attributes.
GlossEntry
An entry in a Glossary.
It contains, in order, a required
GlossTerm, an optional Acronym,
an optional Abbrev, and any number of
GlossSees and GlossDefs, in any order.
It has common attributes.
GlossSee
A cross-reference from one
GlossEntry to another. It may contain plain
text or no content, and has common and OtherTerm
attributes. OtherTerm is a reference to the
GlossTerm within the cross-referenced GlossEntry; that
GlossTerm should be displayed at the point of the GlossSee.
GlossSeeAlso
A cross-reference from one
GlossDef to another GlossEntry. It may contain plain
text or no content, and has common and OtherTerm
attributes. OtherTerm is a reference to the
GlossTerm within the cross-referenced GlossEntry; that
GlossTerm should be displayed at the point of the GlossSee.
GlossTerm
A term in the
text of a Chapter (for example) that is glossed in a Glossary; also used for those terms in GlossEntries, in the
Glossary itself. As you may not want to tag all occurrences
of these words outside of Glossaries, you might consider
GlossTerm, when used outside of Glossaries, to be similar
to FirstTerm, except that GlossTerm may contain other
in-line elements. GlossTerm contains in-line elements
and has common attributes.
Glyph
A mark, a component of a font. A character
or ligature might be made up of one, two, or more Glyphs.
Cf. Character.
It contains plain text and has common attributes.
Graphic
Encloses graphical data or
points via an attribute to an external file containing such data,
and is to be rendered as an object, not in-line.
It has Format,
Fileref, Entityref, and ID attributes.
The format attribute may have the value of
any of the formats defined at the head of the DTD,
including CGM-CHAR, CGM-CLEAR, DITROFF, DVI, EPS,
EQN, FAX, FAXTILE, GIF, IGES, PIC, PS, TBL, TEX,
TIFF.
The value of
Fileref should be a filename, qualified by a pathname
if desired; the value of Entityref should be that of an
external data entity. If data is given as the
content of Graphic, both Entityref and Fileref,
if present at all, should
be ignored, but a Format value should be supplied.
if no data is given as the content of
Graphic and a value for Entityref
is given, Fileref, if present, should be ignored
but no Format value should be supplied.
Finally, if there is no content for Graphic and
Entityref is absent or null, Fileref must be
given the appropriate value, and again no
Format value should be supplied.
Group
A group of constituent parts of a
CmdSynopsis. A Group consists of one or more Args, Groups,
SynopFragmentrefs,
and Replaceables, in any order. See CmdSynopsis.
Group has common, grpchcatt, and repatt attributes.
argchcatt or “argument choice attribute”
resolves to the attribute
Choice, with allowed values Opt (the Arg is
optional; the default), Req (it is required), and Plain (neither
optional nor required).
repatt or “repetition attribute”
resolves to the attribute Rep, with allowed
values Norepeat (the Arg may be repeated; the default)
and Repeat (the Arg does not repeat).
grpchcatt or “group choice attribute”
is a parameter entity that
resolves to the the Choice attribute for the element Group.
The allowed values are Opt (the Arg is
optional; the
default), Req (it is required), Plain (neither
optional nor required), OptMult (optional and
repeatable), and ReqMult (required
multiple times).
Hardware
A physical part of a computer system.
It may contain members of cptrphrase.gp,
and has common and MoreInfo attributes.
For the MoreInfo
attribute see Application.
Highlights
A list of main points discussed
in a book component such as a Chapter. It may contain
paragraphs,
lists, and admonitions, and has common attributes.
Holder
Part of Copyright; the
holder of the copyright of the document. It contains
plain text.
Honorific
A person's title, to be used as part of
Author, Editor, or OtherCredit. It contains
plain text.
HWapplic
Dropped. See Application.
Icon
Dropped. See Interface.
Important
An admonition set off from the text.
See Caution.
Index
An index to a Chapter,
Appendix, Preface, or Book.
It contains an optional DocInfo, Title, and TitleAbbrev,
followed by
any number of block-oriented elements,
and then one or more IndexEntries or one or more IndexDivs.
It has common attributes.
IndexAs
Dropped.
IndexDiv
A division of an Index.
It may have a Title and TitleAbbrev,
some optional introductory matter (block-oriented elements,
Anchors, Comments), and must then
contain one or more IndexEntries or a SegmentedList (use
a SegmentedList for a permuted index).
It has common attributes.
IndexEntry
Part of Index. It contains a
PrimaryIE, which may be accompanied by SecondaryIE,
TertiaryIE, SeeIE, and SeeAlsoIE. It has common attributes.
IndexTerm
A character string to be indexed,
occurring in the text flow but not in the text itself.
(And remember, IndexTerm appears in the text,
not in the Index!)
Primary, Secondary, and Tertiary
index items are nested within this tag, as are See and
SeeAlso items. It has common, SpanEnd, PageNum, and
Significance attributes.
The SpanEnd attribute may not be used if IndexTerm
has content; it should be used only
to mark the end of a span
of text that begins earlier
at an IndexTerm that does have
content.
The value of SpanEnd must be the
ID of that earlier IndexTerm.
The PageNum attribute may be used to
indicate the page on which the indexed term is found in print. Significance
may have the value Preferred, indicating that the
entry is the most pertinent of the series, or Normal (the
default).
InformalEquation
An untitled mathematical equation
displayed on a line by itself, rather than in-line.
It contains a Graphic, and
has common attributes.
InformalTable
An array of text that has no Title.
Otherwise, it is just like Table except that it lacks the
ShortEntry and ToCEntry attributes. See Table.
InlineEquation
An untitled mathematical equation
occurring in-line or as the content of an Equation.
It contains a Graphic, and has common attributes.
InlineGraphic
Encloses graphical data or
points via an attribute to an external file containing such data,
and is to be rendered in-line.
InlineGraphic has Format, Fileref, Entityref, and
ID attributes.
The format attribute may have the value of
any of the formats defined at the head of the DTD,
under “Notations.”
If it is desired to point to an external file, a filename may
be supplied as the value of the Fileref attribute, or an
external entity name may be supplied as the value of the
Entityref attribute.
Interface
Any part of a graphical user
interface.
It may contain members of cptrphrase.gp,
and has common, Class, and MoreInfo attributes.
Class may have the value Button, Icon, Menu, or MenuItem
(no default). For the MoreInfo
attribute see Application.
InterfaceDefinition
A specification for a graphical user
interface. It may contain members of cptrphrase.gp,
and has common and MoreInfo attributes.
For the MoreInfo
attribute see Application.
InvPartNumber
An inventory part number. It contains plain text.
ISBN
International
Standard Book Number of a document. It contains plain text.
ISSN
International
Standard Serial Number of a journal. It contains plain text.
IssueNum
The number of an issue of a journal.
It contains plain text.
ItemizedList
A list in which each item is marked with
a bullet, dash, or other dingbat (or no mark at all).
It consists of one or more ListItems. A ListItem in an
ItemizedList contains paragraphs and other
block-oriented elements, which
may in turn contain other lists; an ItemizedList may be
nested within other lists, too.
It has common attributes and
a Mark attribute. Your application might supply the mark to be used
for an ItemizedList, but you can use this attribute to
indicate the mark you desire to be used; there
is no fixed list of these.
Usage Note:
You might want to use one of the ISO text entities
that designates an appropriate dingbat.
JobTitle
Part of Affiliation. It contains
plain text.
JournalInfo
Information about the journal in
which an Article appears, in that Article's ArtHeader.
It contains, in order, a required Title, optional
TitleAbbrev, Subtitle, ISSN, VolumeNum, IssueNum,
PageNums, PubDate, Publisher, and Copyright.
KeyCap
The text printed on a physical key on a
computer keyboard, not necessarily the same thing as a
KeyCode. It may contain members of cptrphrase.gp,
and has common and MoreInfo attributes.
For the MoreInfo
attribute see Application.
Keycode
The computer's numeric designation of a key on
a computer keyboard. Keycode contains plain text and has common
attributes.
Keysym
A key symbol name, which is not
necessarily the same thing
as a Keycap. For example, the Keysym for
the H key (Keycap H) might be h.
It contains plain text, and
has common attributes.
LegalNotice
An
acknowledgement of trademarks, etc. It
may have a Title, followed by paragraphs,
and BlockQuotes in any order.
Lineage
Part of an author's name, such
as “Jr.” It contains plain text.
LineAnnotation
A writer's or editor's comment on
a line of program code within an Example, ProgramListing,
or Screen. LineAnnotations are a document author's
comments on the code, not the comments written
into the code itself by the code's author.
Link
A hypertext link. At present, all
the link types represented in the DTD are
provisional. Link is less provisional than the
others, however. In HyTime parlance, Link is a
clink. It may contain in-line elements
and has Endterm, Linkend, and Type attributes. The required
Linkend attribute specifies the target of the link,
and the optional Endterm attribute specifies
text that is to be fetched from elsewhere in the document
to appear in the Link. You can also supply this text directly as
the content of the Link, in which case the
Endterm attribute is to be ignored (new and tentative
rule for this version, comments invited).
ListItem
A wrapper for the elements of
items in an ItemizedList or OrderedList; it also
occurs within VarListEntry in VariableList.
It may contain just about anything except Sects and book
components.
It has common attributes and an Override attribute, which
may have any of the values of ItemizedList's
Mark attribute; use Override to override the mark
set at the ItemizedList level, when you desire to create
ItemizedLists with varying marks.
Literal
Any literal string, used in-line, that is part of
data in a computer. This may be as precise as
the value of an argument, but Literal may also be used
as a catch-all element.
It may contain members of cptrphrase.gp,
and has common and MoreInfo attributes.
For the MoreInfo
attribute see Application.
LiteralLayout
The wrapper for lines set off from
the main text that are not tagged as Screens, Examples,
or ProgramListing, in which line breaks and leading
white space are to be regarded as significant.
It contains in-line elements, and has common
and Width attributes, for
specifying a number representing the maximum width of
the contents.
LoT
The generic tag for such things as a List
of Figures or List of Tables. An LoT may occur within a Chapter, or Appendix, or may be a book
component on its own.
It contains, in order, an optional DocInfo, Title, and TitleAbbrev,
followed by one or more LoTentries. It has
common and Label attributes; in this case the values of
Label may be Equation, Examples, Figures, or Tables,
with no default.
LoTentry
An element of LoT. It contains
the text of the thing to be listed,
including, if desired, in-line elements. It has
common and PageNum attributes.
Macro
Dropped. See SystemItem.
ManVolNum
Specific to UNIX man pages, it
designates the section of a complete set of
reference pages that a reference page belongs to. It appears
within RefMeta, contains plain text, and has common
attributes.
Markup
A string of formatting markup in text,
which it is desired to represent literally. See also
SGMLTag.
It contains plain text and has common attributes.
Mask
Values in a specified structure that should
be read when updating resource values.
Mask contains plain text and has common attributes.
MediaLabel
The physical medium on or in which
some information is contained.
MediaLabel may contain plain text,
and has common, Class, and MoreInfo attributes.
Class may have the value Cartridge, CDRom, Disk, or Tape
(no default). For the MoreInfo
attribute see Application.
Member
Part of a SimpleList. It contains
in-line elements and has common attributes.
Menu
Dropped. See Interface.
MenuItem
Dropped. See Interface.
ModeSpec
Contains application-specific
information necessary for
the completion of an OLink; see
OLink.
Msg
The part of a MsgEntry that contains
the error message and its subparts, along with
explanatory text. A Msg has a required MsgMain,
followed by any number of MsgSubs and MsgRels, in any
order. It has common and Label attributes.
MsgAud
Describes the audience
to which a Msg is
relevant. It contains plain text only, and
has common attributes.
MsgEntry
A wrapper for an entry in a MsgSet.
A MsgEntry
must contain one or more Msgs, followed by an optional
MsgInfo, then any number of MsgExplans.
MsgEntry has common
attributes.
MsgExplan
Holder for any kind of explanatory
material relating to the
Msg. MsgExplan begins with an optional Title
(typically something such as
“Explanation:” or “Action:”)
and may contain block-oriented elements.
It has common attributes.
MsgInfo
Information about the Msg
containing it. It may have any number of MsgLevels,
MsgOrigs, and MsgAuds, in any order, and has common
attributes.
MsgLevel
The level of importance or severity
of a Msg. It contains only plain text, and has common
attributes.
MsgMain
The main error message of a
Msg. MsgMain begins with an optional Title and contains
MsgText, which is the text of the message. It
has common attributes.
MsgOrig
The origin of a Msg.
It contains only plain text and has common attributes.
MsgRel
An optional subpart of a Msg, containing
a message that is related to the main message
(MsgMain) but which appears in a
different place. For example, MsgMain
might be a message that appears on a
network client, and MsgRel a related message
that appears at the
server console in response to the same condition or event.
MsgRel begins with an optional Title and contains
MsgText. It has common attributes.
MsgSet
A list of error messages produced
by a system, with various additional information.
MsgSet contains one or more MsgEntries, and has
common attributes.
Usage Note:
The entire Msg* construction is new and complicated;
it may be simplified in the future.
MsgSub
An optional subpart of a Msg, which
might contain messages that appear in various contexts. It
contains a an optional Title followed by
MsgText. MsgSub has common attributes.
MsgText
Contents of the parts of Msg.
It may contain block-oriented elements,
and has common attributes.
Note
A message to the user, set off from the text.
See Caution.
OLink
A link that may perform some operation to
find its target. In contrast to Link, OLink has no
Linkend attribute, but rather a TargetDocEnt, the value of
which is the name of a text or data entity already
defined by the user. The LinkMode attribute points by
ID to a ModeSpec; for convenience, ModeSpecs
located in the BookInfo. ModeSpec contains
instructions (probably application-specific) for operating
on the entity named by TargetDocEnt, e.g., the
TargetDocEnt is another Book, and the ModeSpec specifies
that all the second-level headings should be searched
for a phrase. The LocalInfo attribute may be used to
hold such a phrase, which may be thought of as a
replacement for some variable in ModeSpec. Finally,
OLink has a Type attribute, also.
Option
An option for a computer program command.
It may have members of cptrphrase.gp, and has common
attributes.
Optional
For use in Synopsis, as in a
RefEntry, where optional parameters
conventionally are shown in square
brackets. Optional should replace those brackets. It may contain
elements from cptrphrase.gp, and has common attributes.
OrderedList
A numbered or lettered list, consisting of
ListItems. A ListItem in an
OrderedList contains paragraphs and other
block-oriented elements, which
may in turn contain other lists; an OrderedList may be
nested within other lists, too.
OrderedList has common attributes, along with
a Numeration attribute, which
may have the value Arabic, Upperalpha, Loweralpha,
Upperroman, or Lowerroman. If no value is supplied,
the processing expectation should be that Arabic
numbering (1, 2, 3, . . .) is to be used.
It has an InheritNum attribute, for which the
value Inherit specifies for a
nested list that the numbering of ListItems should include the
number of the item within which they are nested (2a, 2b, etc.,
rather than a, b, etc.); the default value is Ignore.
It has a Continuation attribute, with values
Continues or Restarts (the default),
which may be used to
indicate whether the numbering of a list begins afresh (default)
or continues that of the immediately preceding list (Continues).
You need supply the Continuation attribute only
if your list continues the numbering of the preceding list.
OrgName
An organization that is not
a corporation (cf. CorpName)
It contains plain text.
OrgDiv
Part of an organization.
It contains plain text.
OSname
Dropped. See SystemItem.
OtherCredit
Supplements
Author and Editor; you could use it to credit a contributor,
a contributing editor, or some deserving production person.
Contents are as for Author. It has common
attributes.
OtherName
An alternative to Firstname and
Surname, for use in Author, Editor, or OtherCredit.
It contains plain text.
PageNums
The numbers of the pages contained
in a Book, for use in its BookBiblio.
It contains plain text (e.g., ix, 292).
Para
A paragraph. A Para may not
have a Title: to attach a Title to a Para use
FormalPara. Para
may contain any in-line element and almost
any block-oriented element. Abstract, AuthorBlurb, Caution,
Important, Note, and
Warning are excluded, as are Sects and higher-level
elements. Para has common attributes.
Paragraphs
See Para.
ParamDef
Part of a FuncSynopsis, providing
data type information and the name of the
Parameter this information applies
to. A ParamDef may contain any combination of
plain text, Replaceable, Data, or Parameter, in any order.
It has common attributes. See FuncDef,
FuncSynopsis. It has common attributes.
Parameter
Part of an instruction to a computer.
It may contain members of cptrphrase.gp,
and has common, Class, and MoreInfo attributes.
Class may have the value Command, Function, or Option
(no default). For the MoreInfo
attribute see Application.
Part
A section of a Book containing
book components.
Part contains an optional DocInfo, a required Title, an optional TitleAbbrev,
an optional PartIntro,
followed by one or more book components.
It has common and Label attributes.
PartIntro
Introduction to the contents
of a Part;
may also appear in
Reference. It has optional Title and TitleAbbrev,
and then may contain anything that can appear in a Chapter.
PartIntro has common and Label attributes.
Phone
Part of Address. It contains plain text.
POB
Part of Address. It contains plain text.
Postcode
Part of Address. It contains plain text.
Preface
Any introductory matter in a Book.
Preface may occur more than once in Book, before
any Chapter, Part, or Reference: for example,
you might have two Prefaces, one titled “Preface”
and the other “Introduction.”
Preface may begin with a DocInfo, followed by
a required Title, optional TitleAbbrev, and anything
found in the body of a Chapter.
Preface has common attributes.
Primary
A word or phrase occurring in
the text that is to
appear in the index under as a primary entry. It must be
nested within IndexTerm tags. Primary may contain in-line
elements. It has SortAs and common attributes.
SortAs can be used to provide
an alternate string for alphabetizing the index: if Primary
has the content “14”
one might give Primary the attribute
Sortas=“fourteen”.
PrimaryIE
A primary entry in an Index, not in the
text. It may contain only plain text. It has common
attributes and a Linkends attribute, which has the
value of some list of element IDs.
PrintHistory
The printing history of
a Book. It contains paragraphs.
Procedure
A list of operations to
be performed. Procedure may have a Title and
TitleAbbrev, followed by block-oriented elements,
such as paragraphs, followed by one or more Steps.
A Step may have a SubSteps wrapper for Steps nested
within it, and this nesting may continue indefinitely
(contrast the methods of nesting lists and Sects).
This construction is intended to maximize the reusability
of subsections of Procedures.
Procedure has common attributes.
ProductName
Formal name for any product.
It contains in-line elements, and has common and
Class attributes. The Class attribute may have the
values Service, Trade (the default), Registered, Copyright,
or Logo. Thus a trademark is a Productname with the
default Class attribute value.
ProductNumber
A number assigned to a product.
It contains plain text.
ProgramListing
A listing of a program.
Line breaks and leading
white space are significant in a ProgramListing, which
may contain in-line elements, including LineAnnotations.
(LineAnnotations are a document author's
comments on the code, not the comments written
into the code itself by the code's author.)
ProgramListing has common and Width attributes, the
latter for specifying a number representing the maximum
width of the contents.
Prompt
Dropped. See SystemItem.
Property
A defined set of data
associated with a window. It may contain members of cptrphrase.gp,
and has common and MoreInfo attributes.
For the MoreInfo
attribute see Application.
ProtocolRequest
Message sent from a program to a
server. It may contain members of cptrphrase.gp,
and has common and MoreInfo attributes.
For the MoreInfo
attribute see Application.
PubDate
The date of publication of a document.
It contains plain text.
Publisher
The publisher of a document. It contains a PublisherName and any number of Addresses.
PublisherName
The name of a publisher of a document. It contains plain text.
PubsNumber
A number assigned to a publication,
other than an ISBN or ISSN or InvPartNumber.
It contains plain text and has common attributes.
Quote
An in-line quotation. For block quotes
use BlockQuote. Quote may contain members of cptrphrase.gp,
and has common attributes.
RefClass
An element of RefNameDiv, in which the
applicability or scope of the topic of a RefEntry may be
indicated. It may contain
plain text or Application.
RefDescriptor
A substitute for RefName to be used
when a
RefEntry covers more than one topic and none of the topic names
is to be used as the sort name. It contains plain
text and has common attributes.
RefEntry
A reference page. It contains,
in order, an optional DocInfo and optional RefMeta;
any number of Comments and members of links.gp, in any order;
a required RefNameDiv, an optional RefSynopsisDiv,
and one or more RefSect1s.
It has common attributes.
Reference
A collection of RefEntries,
formin a book component.
Reference has an optional DocInfo,
a required Title,
an optional TitleAbbrev, an optional PartIntro, and
one or more RefEntries.
It has common and Label attributes.
RefEntryTitle
Primary name given to a
reference page for
sorting and indexing. It may be the same as the first of
the RefNames, or it may be the same as the RefDescriptor.
It may contain in-line elements, and has common
attributes.
RefFileName
Dropped. It is now called
RefEntryTitle.
RefMeta
The first major division of a reference page,
in which metainformation about the reference page is supplied.
RefMeta contains, in order, a required RefEntryTitle,
an optional ManVolNum, and any number of
RefMiscInfos. It has common attributes.
RefMiscInfo
Marks information in
RefMeta that may be
supplied by vendors, such as copyright, release date, revision
date, print status, operating system, hardware architecture,
or a descriptive phrase for use in a print header.
It contains plain text, and has common and Class attributes.
The Class attribute can be used to distinguish categories of
RefMiscInfos.
RefName
The subject or subjects of a
reference page. It appears within RefNameDiv.
It may contain plain text and in-line elements, and
has common attributes.
RefNameDiv
The second major division of a reference page.
It contains, in order, an optional RefDescriptor, one or more
RefNames, a required RefPurpose, and an optional RefClass,
followed by any number of Comments and links, in any order.
It has common attributes.
RefPurpose
A short phrase describing the
subject of
the reference page. It may contain in-line elements
and has common attributes.
RefSect1
Equivalent to a Sect1 in the DocBook DTD.
It contains a Title, followed by any of the allowable contents
of a Sect, except that only two levels of subsection
are allowed, RefSect2 and RefSect3. It has common attributes.
RefSect2
Equivalent to a Sect2 in the DocBook DTD, and may
occur within RefSect1 or RefSynopsisDiv. It may contain any of the
allowable contents of a Sect, except that only RefSect3
is allowed as a further subsections. It has common attributes.
RefSect3
Subdivision of RefSect2. No further
subdivisions allowed; contents otherwise as for RefSect2.
It has common attributes.
RefSynopsisDiv
The third major division of a reference page,
in which the syntax of the subject of the reference page is
indicated. It contains, in order,
an optional Title and TitleAbbrev, followed by either one or more
synopses (Synopsis, CmdSynopsis, or FuncSynopsis) succeeded
by any number of RefSect2s, or simply one or more RefSect2s.
It has common attributes.
ReleaseInfo
Information about a particular version of a
document. It contains plain text.
Replaceable
Part of a synopsis or command line,
indicating that its contents may be replaced.
It may contain basic in-line elements (not cptrphrase.gp)
and has common and Class attributes.
Class may have the value
Command, Function, Option, or Parameter
(no default).
Resource
Dropped. See SystemItem.
ReturnValue
A value returned by a function.
It contains plain text and has common attributes.
RevHistory
A section of BookInfo or DocInfo
recording revisions to the document. It
consists of any number of Revisions, and
has common attributes.
Revision
An entry in RevHistory,
describing some
revision made to the text. It contains, in order,
a required RevNumber, required Date,
one or more sets of AuthorInitials, and
a required RevRemark.
RevNumber
The number of a Revision.
It contains plain text.
RevRemark
An element
of Revision, describing the Revision.
It contains plain text.
Row
A row in a TBody, THead, or TFoot.
It contains one or more Entries or
EntryTbls, in any order.
It has common, Rowsep, and VAlign attributes.
Rowsep determines Row separators. If its content is
Yes, display the internal vertical row ruling
below each Row; if No, do not display it. It is
ignored for the last Row of the TGroup, THead,
or TFoot, where
the frame value applies. There is no default.
The value is inherited from TGroupStyle, if used.
Valign governs the vertical
positioning of text within a Row.
Allowed values are Top, Middle, and Bottom
(no default).
Screen
Intended to represent what the user sees or
might see on a computer screen. It
consists of in-line elements, in which line breaks
and leading white space are considered
significant. It has common attributes and a Width
attribute for specifying a number representing the maximum width of
the contents.
ScreenInfo
Part of ScreenShot
(see ScreenShot). A ScreenInfo
indicates how the Graphic with which it is paired was created,
as a guide for future revisions. It may contain only plain
text, and has common attributes.
ScreenShot
Like Screen,
intended to represent what the user sees or
might see on a computer screen. It
consists of an optional ScreenInfo
and a required Graphic.
It has common attributes and a Width
attribute for specifying a number representing the maximum width of
the contents.
Secondary
A word or phrase in the text that is to
appear in the index beneath a Primary entry. It must be
nested within IndexTerm tags and must follow a Primary element.
It may contain in-line elements, and has
SortAs and common attributes. See Primary.
SecondaryIE
Part of IndexEntry,
like PrimaryIE (see PrimaryIE).
Sect1
A top-level section of a book component,
including the Title of that section. Sect2–5 nest
in order within Sect1. Anything may occur
within a Sect1 except a DocInfo, Preface,
Chapter, Appendix, or
another Sect1, including a Glossary, Bibliography, RefEntry, ToC, Index,
or LoT. A Sect must have a Title, which is the text
of the heading itself, and may have a TitleAbbrev; it must
include some content, whether paragraphs or other block-oriented elements, including
a Sect2. Sect1–5 have common,
Label, and Renderas attributes. The Renderas attribute may
have the value Sect1 through Sect5, and may be used to
specify that the Sect (particularly its heading) is to be
presented in the format defined for a Sect of some other level.
Sect2
A section beginning with a second-level
heading; must be nested within a Sect1.
Allowable and required contents
for Sect2, and its attributes, are like those for Sect1.
Sect3
See Sect1, Sect2.
Sect4
See Sect1, Sect2.
Sect5
See Sect1, Sect2. Sect5 may
not contain Sects of any level, and
no further subdivisions are supplied in the DocBook DTD.
See
Part of IndexTerm, indicating, for
a word or phrase in the text, the index entry to
which the reader is to be directed when he consults
the stub index entry for another element within
the IndexTerm.
See must be nested within IndexTerm tags and must
follow a Primary or Secondary element.
It may contain in-line
elements, and has common attributes.
SeeAlso
Like See, but indicates
the index entries to which the reader is also
to be directed when he consults a full index entry.
SeeAlso must be nested within IndexTerm tags and must
follow a Primary or Secondary element.
It may contain in-line
elements, and has common attributes.
SeeAlsoIE
A “see also” entry in an Index, not
in the text, occurring
unnested within IndexEntry at the PrimaryIE or
SecondaryIE level.
It may contain plain text only. It has common
attributes and a Linkends attribute, which has the
value of some list of IndexEntry IDs.
SeeIE
A “see” entry in an Index, not in the
text, occurring
unnested within IndexEntry at the PrimaryIE or
SecondaryIE level.
It may contain plain text only. It has common
attributes and a Linkend attribute, which has the
value of some IndexEntry ID.
Seg
A component of a SegmentedList. Segs are the
only content of a SegmentedList's
SegListItems. Seg may contain in-line
elements. It has common attributes.
SegListItem
A list item in a SegmentedList.
It consists
of two or more Segs, and has common attributes.
SegmentedList
A list of sets of units.
It may be used to represent
sets of information often presented as simple tables.
SegmentedList may have a Title and TitleAbbrev, followed by any number
of SegTitles, and one or more SegListItems.
It has common attributes.
SegTitle
A title that pertains to one Seg in each
SegListItem: the first SegTitle to the first Seg, the second SegTitle
to the second Seg, and so on. It may contain in-line elements.
SegTitles
are grouped at the beginning of a SegmentedList, before the SegListItems.
It has common attributes.
Series
Dropped.
SeriesInfo
Part of BookInfo or BiblioEntry,
containing information about the publication series of
which the book is a part. SeriesInfo contains,
in order, a
required Title, optional TitleAbbrev and Subtitle;
any number of AuthorGroups, optional ISBN,
VolumeNum, and IssueNum; a required SeriesVolNums,
any number of PubDates and Publishers, and finally
an optional Copyright.
It has common attributes.
SeriesVolNums
The numbers of all the volumes
in a Series, for use in SeriesInfo. It contains plain text
(e.g., 1-5).
Set
Two or more Books. Set may have,
in order, a
Title, TitleAbbrev, SetInfo, and ToC, followed by
the Books, followed by an optional SetIndex. Note that
a SetIndex may appear in a Book, too.
Set has common attributes.
SetIndex
Index to a Set. It may
occur within a Set or one of the Books in a Set.
It contains an optional DocInfo, Title, and TitleAbbrev,
followed by any number of block-oriented elements
and then one or more IndexEntries or one
or more IndexDivs.
It has common attributes.
SetInfo
Metainformation for a Set,
in which it may appear. It may contain, in any order,
any number of: Author, AuthorInitials,
Copyright, CorpAuthor, CorpName, Date,
Editor, Edition, InvPartNumber, ISBN, LegalNotice,
OrgName, OtherCredit,
PrintHistory, ProductName, ProductNumber,
Publisher, PubsNumber, ReleaseInfo, RevHistory,
Title, Subtitle, and VolumeNum.
SetInfo has common attributes and a Contents attribute.
Contents is partly a stub for future development; at the
moment its values should be the IDs of the ToC, Books,
and SetIndex that comprise the Set, in the order of
their appearance.
SGMLTag
An element tag in SGML. This
element contains plain text, and should not include
delimiting angle brackets, ampersands,
percent signs, or semicolons: those should be
supplied by the renderer if appropriate. It has common and Class
attributes. Class may be Attribute, Element,
GenEntity, or ParamEntity; there is no default.
ShortAffil
Brief version of of Affiliation, in
which it may appear. It contains
plain text.
Sidebar
Segment of a book component
that is isolated from the narrative flow
of the main text, typically boxed and floating.
Sidebar may have
a Title and a TitleAbbrev, followed by
paragraphs, lists, and other block-oriented
elements. No Sects allowed.
Sidebar has common attributes.
SimPara
A paragraph that is only a text block,
without included block-oriented elements. It
may contain InlineGraphic, InlineEquation, and synopses.
SimPara has common attributes.
SimpleList
Intended for long lists of single words
or short phrases. It consists of one or more Members, and
has common, Columns, and Type attributes. The value of
the Type attribute may be Inline, Horiz, or Vert (the
default), indicating that the list should be formatted
as part of a regular paragraph, as an array reading L to R
then top to bottom, or
as an array reading top to bottom then L to R.
The Columns attribute value must be a number, the number
of columns the array should contain. Further details
on rendering may be found in the comment in the DTD,
but these details may required some revision in the
future.
SpanSpec
Formatting information for a
spanned column in a TGroup (part of Table).
SpanSpec is an empty element, bearing common, Align,
Char, Charoff, Colsep, Nameend (required),
Namest (required), Rowsep, and Spanname,
(required) attributes.
SpanSpec identifies a horizontal span of
columns and associated attributes that can
subsequently be referenced by its SpanName to
provide attributes repeatedly used in the Entries or
EntryTbls in the Rows of the TGroup that is
nested within the THead, TFoot, or TBody in which the
SpanSpec occurs.
The reason Colname is used rather than Colnum
in identifying
SpanSpec is that the names are independent of revisions that
may change the number of inserted/deleted columns, as
long as Namest remains to the left of (has a smaller colnum
than) Nameend. SpanSpecs set on THead or TFoot override
those on the containing TGroup and apply to just the THead
or TFoot. SpanSpecs from the containing TGroup apply to
TBody.
Align controls the horizontal position
of text within the column.
The value of Align may be Left (quad flush left),
Center (centered), Right (quad flush right),
Justify (both quad left and right), or Char (align to the
left of Char, positioned by Charoff). The default
is Center.
Char contributes to Align. If the
value of Align is “char”, the value of Char
should be a character on the first occurrance
of which the entry is to be aligned. If that
character does not occur in the entry, the entry
is aligned to the left of the position determined
by Charoff. The default is inherited
from the ColSpec of the column named by Namest.
Charoff contributes with Char to Align.
Charoff is the proportion
of the current column width, expressed in percentage,
to be allowed before the left edge of the first occurrence
of the character given as the value of Char, if any.
The default is inherited from the ColSpec of
the column named by Namest.
Colsep determines column separators. If its value
is Yes, display the internal column rulings to
the right of each item; if No, do not
display it. It is ignored for the last column, where the
Frame setting applies. (In CALS,
Yes is expressed as 1 and No as 0.)
The default is inherited from the ColSpec of
the column named by Namest.
Nameend is the name of the rightmost
column of the span. Names are identified in the
Colspec of the current TGroup.
Namest or Name Start,
is the name of the leftmost column
of the span. Names are identified in the
Colspec of the current TGroup.
Rowsep determines Row separators. If its content is
Yes, display the internal vertical Row ruling
below each item; if No, do not display it. It is
ignored for the last Row of the table, where
the frame value applies. There is no default.
The value is inherited from the ColSpec of
the column named by Namest.
Spanname is the name of the
horizontal span.
State
Part of Address. It contains plain text.
Step
Part of a Procedure. After its
optional Title, Step must consist either
of block-oriented elements such as
paragraphs followed optionally by a SubSteps element,
or simply a
SubSteps element. SubSteps then contains one or more
Steps—it is a wrapper.
Step has common attributes
and a Performance attribute, which indicates whether
the step must be performed: the values are Optional
and Required (the default).
Street
Part of Address. It contains plain text.
StructField
A field in a Structure.
It contains plain text and has common attributes.
StructName
The name of a Structure. It contains
plain text and has common attributes.
SubSteps
A wrapper for Steps within Steps.
See Procedure, Step. Note that SubSteps, like
Step, has a Performance attribute, the values of which
may be Optional or Required (the default).
Subscript
A subscript.
It may contain basic in-line elements and Replaceable,
and has common attributes.
Subtitle
Subtitle of a document.
It contains plain text.
Superscript
A superscript.
It may contain basic in-line elements and Replaceable,
and has common attributes.
Surname
(Western-style) family name
of an author. It contains plain text.
SWapplic
Dropped. See Application.
Symbol
A name that is replaced by a value before
processing. It contains plain text and has common
attributes.
Synopsis
The
syntax of a command or function. It appears
within RefSynopsisDiv, and may occur elsewhere in
a document, too.
Synopsis has an optional title, followed by one or more
in-line elements and Graphics; within it,
line breaks and white space are significant.
It has common attributes. CmdSynopsis and FuncSynopsis
are alternates to Synopsis, but they may not contain
Graphics and within them line breaks and white space are
not significant. Synopsis should be displayed as
a block-oriented element, not in-line.
SynopFragment
Part of CmdSynopsis. It contains
one or more Args or Groups, in any order, and has
the attributes ID (the only required attribute),
Lang, Remap, Role, and XRefLabel.
SynopFragmentRef
Part of a CmdSynopsis. It
contains RCDATA (characters, in which entity
references and character references are
recognized in parsing) rather than elements.
It has common and Linkend (required) attributes.
Linkend should point to SynopFragment.
SystemItem
Any system-related item.
It may contain members of cptrphrase.gp,
and has common, Class, and MoreInfo attributes.
Class may have
the value Constant, EnvironVar, Macro, OSname, Prompt,
Resource, or SystemName
(no default). For the MoreInfo
attribute see Application.
SystemName
Dropped. See SystemItem.
Table
An array of text.
The Table models available in version 1.2.2 have been
dropped in favor of a CALS-compliant Table model.
The present Table element has a required Title,
an optional TitleAbbrev, and either one or more Graphics
or one or more TGroups. Tables may not contain
either Tables or InformalTables.
Table has common, Colsep, Frame, Label, Orient, Pgwide, Rowsep, Shortentry,
Tabstyle, and Tocentry attributes.
elements that may be contained within
TGroup are specified as having omissible
end tags, except for EntryTbl. Who said the military
isn't thoughtful?
Colsep determines column separators. If its value
is Yes, display the internal column rulings to
the right of each item; if No, do not
display it. It is ignored for the last column, where the
value of Frame applies. There is no default; the
value may be inherited from Tabstyle in the FOSI.
Frame describes the positioning of
framing rules around the Table. The allowed values are
Sides (left and right), Top (below title),
Bottom (after last Row, possibly the last Row of
TFoot), Topbot (both top and bottom), All
(all of the aforementioned), and None.
There is no default. The value may be
inherited from Tabstyle in the FOSI.
Label is just the same as DocBook's
Label attribute: a reference string, such as a
number, to be prefixed to the Title.
Orient determines the orientation of the
Table. The allowed values are Port (the orientation
of the rest of the text of the Book, that is, upright)
and Land (90 degrees counterclockwise from the
orientation of the rest of the text of the Book).
If you assume that the page is taller than
it is wide, tables that take up a whole page and
are wider than they are tall should be given the Land value.
There is no default, the value may be
inherited from the FOSI.
Pgwide constrains the table to
or liberates it from the boundaries of its
column. If the value is
Yes, the table runs
across the entire page; if No, the table “runs
across just the (galley) width of the
current column of the page, regardless
of the value of Orient. If the
value is No, it has no meaning for the case when
Orient is set to Land.
The value may be inherited from Tabstyle in
the FOSI, if available.
Rowsep determines row separators. If its content is
Yes, display the internal vertical row ruling
below each item; if No, do not display it. It is
ignored for the last row of the table, where
the value of Frame applies. There is no default.
The value may be inherited from TabStyle.
Shortentry determines whether value of ShortEntry is be used
in the an Index or ToC or LoT. If the value is No,
the TitleAbbrev is not used; if Yes, the ShortEntry
is used.
Usage Note: Be aware that
this mechanism duplicates the DocBook element
TitleAbbrev. It would be better, for any given
work, to choose one mechanism
or the other, rather than mix them.
Tabstyle is the name of
a table style defined in the FOSI. There is no default.
Tocentry determines whether the
Table's Title should be included in an LoT.
The value may be Yes (include) or No (exclude).
The default is Yes (include).
should be ignored if the optional Title is
omitted; that would be the case if you were using Table,
instead of InformalTable, for a Table that has no
Title; presumably only a reference string could then
appear in an LoT.
Term
The hanging term attached to a ListItem
within a VarListEntry in a
VariableList; visually, a VariableList
is a set of Terms with attached items such as paragraphs. Each
ListItem may be associated with a set of Terms. Term may contain
in-line elements or synopses. It has
common attributes.
Tertiary
A word or phrase that is to
appear in the index under a Secondary entry. It must be
nested within IndexTerm tags and must follow a Secondary
element. It may contain in-line elements, and has SortAs
and common attributes. See Primary.
TertiaryIE
Part of IndexEntry, like PrimaryIE
see PrimaryIE).
TBody
Wrapper for the Rows of a Table or
InformalTable. It contains simply one or more Rows,
and has common and VAlign attributes.
VAlign governs the vertical
positioning of text within a Row.
Allowed values are Top (the default), Middle, and Bottom.
TFoot
TFoot is a optional part of TGroup
(part of Table), identifying the footer information in a
Table, which is displayed after the TBody and also at the
bottom of any TBody Rows before a page break.
TFoot must have one or
more Rows. It has common and VAlign attributes, the latter
with the allowed values of Top (the default), Middle
(approximately centered vertically), and Bottom.
TGroup
The part of a Table that is
contains an array along with its formatting information.
In order, a TGroup has any number of ColSpecs,
any number of SpanSpecs, an optional THead, and optional
TFoot, and a required TBody.
Each TGroup effectively identifies a new
portion of a Table. If a new ColSpec is provided, it
replaces a previous one. If both ColSpec and SpanSpec
are new, that SpanSpec should refer to columns in the most
recent ColSpec. If only a new SpanSpec is provided, it
should refer to columns defined by the most immediately
prior ColSpecs in a TGroup of the
Table. On the other hand, a new ColSpec to
either a THead or TFoot replaces all prior column
definitions. TGroup has common, Align, Char, Charoff, Cols,
Colsep, Rowsep, and TGroupStyle attributes.
Align controls the horizontal position
of text within the column.
The value of Align may be Left (quad flush left),
Center (centered), Right (quad flush right),
Justify (both quad left and right), or Char (align to the
left of Char, positioned by Charoff). The default
is Left, unless overridden by TGroupStyle.
Char contributes to Align. If the
value of Align is “char”, the value of Char
should be a character on the first occurrance
of which the entry is to be aligned. If that
character does not occur in the entry, the entry
is is aligned to the left (the original doc incorrectly
specifies “right”) of that character.
The default is “”, unless inherited
from TGroupStyle.
Charoff contributes with Char to Align.
Charoff is the proportion
of the current column width, expressed in percentage,
to be allowed before the left edge of the first occurrence
of the character given as the value of Char, if any.
The default is 50 unless overridden by TGroupStyle.
Cols is the number of columns in the table
(required).
Colsep
determines column separators. If its value
is Yes, display the internal column rulings to
the right of each item; if No, do not
display it. It is ignored for the last column, where the
value of Frame applies. There is no default. The
value is inherited from TGroupStyle, if used.
Rowsep
determines row separators. If its content is
Yes, display the internal vertical row ruling
below each item; if No, do not display it. It is
ignored for the last row of the table, where
the value of Frame applies. There is no default.
The value is inherited from TGroupStyle, if used.
TGroupStyle is a unique table group
style defined in a FOSI (no default).
THead
THead is a optional part of TGroup
(part of Table). THead may have any
number of ColSpecs, followed by one or more required
Rows. It has common and VAlign attributes, the latter
with the allowed values of Top, Middle, and Bottom
(the default).
THead identifies the heading information in a Table,
which is displayed at the top of
the Table and again at the top of any continuation after a
page break between Rows in TBody.
Tip
A suggestion to the user, set off from
the text. See Caution.
Title
The text of a heading or the title of a
block-oriented element. Title may contain
in-line elements, and has common and PageNum attributes.
TitleAbbrev
An optional, abbreviated
version of any Title.
You may want to use this element when a
title is so long that it might be truncated in
some part of an online display, such as a title bar.
TitleAbbrev may contain
in-line elements and has common attributes.
ToC
A Table of Contents, which may be
a book component on its own or may
occur within other book components. It may
have a DocInfo, Title, and TitleAbbrev. Formerly,
ToC contained only ToCentry1s, but in this revision
it has been subdivided to follow the divisions of a book:
following the optional Title and
TitleAbbrev, a ToC may have any number of ToCFronts, which
are the entries for the front matter. Following the
ToCFronts, if any, ToC
must have either
one or more ToCParts (entries for Parts)
or ToCChaps (entries for Chapters and Appendices),
and may have any number of ToCBacks
(entries for back matter).
A ToCPart may begin with in-line elements (in all
cases, this is the
actual entry, which was formerly ToCEntry), then contains
any number of ToCChaps. A ToCChap may begin with
in-line elements, then may have any number of ToCLevel1s,
which are entries for Sect1s.
ToCLevel1s may begin with in-line elements, then may have
any number of ToCLevel2s, and so on down to ToCLevel5,
which may have only in-line elements. Thus if you have a
Table of Contents that shows section headings, the second-level entries
are nested within the first-level entries, and so on.
ToC has common attributes.
ToCBack
Entry for back matter in a ToC.
See ToC.
It has common, Linkend, Pagenum, and Label attributes.
The Label attribute may take the value of Bib, Gloss, or
Index,
depending on the identity of the
piece of front matter concerned.
ToCChap
See ToC.
ToCFront
Entry for introductory matter in a ToC.
See ToC.
It has common, Linkend, Pagenum, and Label attributes.
The Label attribute may take the value of Equations, Examples,
Figures, Preface, or Tables, depending on the identity of the
piece of front matter concerned.
ToCLevel1
The top-level tag for entries in a ToC.
See ToC.
ToCLevel2–5 may be nested within it, in order. All
have common attributes and Linkend and
PageNum attributes. PageNum is for indicating the page numbers on which
the Table of Contents entries appear in a printed book. Linkend,
should you choose to use it,
should have the value of the ID of the relevant book part.
ToCLevel1–5 may contain
in-line elements.
ToCPart
See ToC.
Token
A unit of information in the context of
lexical analysis. It contains plain text and
has common attributes.
Trademark
A trademark.
It may contain members of cptrphrase.gp,
and has common and Class attributes.
Class may have the values Service, Trade, Registered,
or Copyright; the default is Trade.
Type
Indicates the classification of a value.
It contains plain text and has common attributes.
ULink
A link containing a URL.
A URL is a Uniform Resource Locator, as used with the
World Wide Web. Very generally,
a URL is a string specifying, according to a defined
protocol, a method,
a path to a target, and possibly some additional information.
The URL should be given as the value
of the URL attribute; there is also a Type attribute.
While ULink is powerful,
it is experimental and may be dropped in future
revisions. Users should not expect
it to be supported by SGML browsers.
UserInput
Data entered by the user.
It may contain elements from cptrphrase.gp,
and has common and
MoreInfo attributes. For the MoreInfo attribute
see Application.
VarArgs
An empty element, part of FuncSynopsis,
indicating that the Function in question
has a variable number of arguments. The string
“(...)” should be output.
VariableList
An optionally
titled list of VarListEntries, which are
composed of sets of one or more Terms with associated
ListItems; ListItems contain paragraphs and other block-oriented
elements in any order. Inclusions
are as for OrderedList (see OrderedList).
VariableList has common attributes.
VarListEntry
A component of VariableList (see VariableList). It has common attributes.
VarParam
Dropped.
Void
An empty element, part of FuncSynopsis,
that indicates that the Function in question
takes no arguments. The string “(void)”
should be output. See VarArgs.
It has common attributes.
VolumeNum
The number of a Book in
relation to Set, or of a journal, when Book
is used to represent a journal by containing
Articles. It contains plain text
and has common attributes.
Warning
An admonition set off from the text.
See Caution.
WordAsWord
A word (or letter or
number) used not to represent the thing or idea it usually
represents, but merely as the word itself. For example,
“The term WORDASWORDGothic/WORDASWORD means different
things to art historians and typographers,” or for a single
character, “the
letter WORDASWORDX/WORDASWORD”.
It contains plain text and has common attributes.
XRef
Cross reference link to another part of the
document.
It has Linkend and Endterm attributes, just like Link,
but like Anchor, it may have no content.
XRef must have a Linkend, but the Endterm is optional.
If it is used, the content of the element it points
to is displayed as the text of the cross reference;
if it is absent, the XRefLabel of the cross-referenced
object is displayed.
See Link.
Year
Year of publication, for use in Copyright.
It contains plain text.