<chapter id=user02>
<title>Object Content in Documents</title>
<sect1>
<title>Terms and Concepts</title>
<para>In this document, <quote>in-line</quote> means <quote>occuring within
a line of text, like a character or character string, not causing a line break.
</quote> This term is sometimes used to refer to objects such as an illustration
around which something like a paragraph is wrapped; here that arrangement
is called <quote>in flow.</quote> 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.</para>
<para>A related point: formal objects have titles (with the possible exception
of a formal equation, which doesn't require a title); informal objects do
not. That an object is informal does not mean that it is in-line: these are
two different characteristics.</para>
<comment>TBS: full-time and part-time (synopsis) inline objects.</comment>
</sect1>
<sect1>
<title>Paragraphs and Text Blocks</title>
<sect2>
<title>Paragraphs</title>
<graphic entityref="paras-tree"></graphic>
<para>DocBook has three kinds of paragraph, regular, simple, and formal: <itemizedlist>
<listitem><para>The regular Para element may contain <sgmltag class="paramentity">
para.char.mix</sgmltag> inline elements and <literal>#PCDATA</literal>, along
with the object-level elements in <sgmltag class="paramentity">para.mix</sgmltag>.
For example, a Para may contain an ItemizedList.</para>
</listitem><listitem><para>The SimPara element contains only <sgmltag class="paramentity">
para.char.mix</sgmltag> inline elements and <literal>#PCDATA</literal>; it
may not contain object-level elements such as lists.</para>
</listitem><listitem><para>The FormalPara element requires a Title and contains
a single Para element.</para>
</listitem></itemizedlist></para>
</sect2>
<sect2>
<title>Abstract and Highlights</title>
<para>An Abstract briefly describes the purpose of a document. A Highlights
element provides highlights to help a reader navigate the material within
a Book component.</para>
<graphic entityref="abstract-tree"></graphic>
<para>An Abstract contains an optional Title, followed by one or more of the
paragraph elements in <sgmltag class="paramentity">para.class</sgmltag>.</para>
<graphic entityref="highlights-tree"></graphic>
<para>A Highlights element contains one or more object-level elements from
the <sgmltag class="paramentity">highlights.mix</sgmltag> mixture.</para>
</sect2>
<sect2>
<title>AuthorBlurb</title>
<graphic entityref="aublurb-tree"></graphic>
<para>An AuthorBlurb briefly describes the author of a document. It contains
an optional Title, followed by one or more paragraph elements from <sgmltag
class="paramentity">para.class</sgmltag>.</para>
</sect2>
<sect2>
<title>BlockQuote and Epigraph</title>
<para>A BlockQuote is an extended, set-off excerpt from another document.
An Epigraph is a brief text, typically a quotation, that is somehow relevant
to a document's content and is set at the beginning of the document. Both
may contain an Attribution element for attribution of the source of their
content.</para>
<graphic entityref="blquote-tree"></graphic>
<para>BlockQuote contains an optional Title, an optional Attribution, and
one or more object-level elements from the <sgmltag class="paramentity">component.mix
</sgmltag> mixture.</para>
<graphic entityref="epigraph-tree"></graphic>
<para>Epigraph contains an optional Attribution and one or more paragraph
elements from <sgmltag class="paramentity">para.class</sgmltag>.</para>
</sect2>
</sect1>
<sect1>
<title>Admonitions and Sidebars</title>
<para>The admonition and Sidebar elements allow you to set off information
that has a special context for proper understanding by readers. Note, Important,
Caution, and Warning set off information that is, for whatever reason, <emphasis>
more important</emphasis> than the surrounding text. Tip sets off information
meant for novice readers who need additional suggestions to work effectively.
Sidebar is like a boxed section within a magazine article: it sets off information
that is related to the main topic but need not be presented in-flow.</para>
<para>In computer documentation, different levels of admonition have precise
meanings related to the consequences of ignoring the contained information.
However, these meanings vary from one company to another. Here is a fairly
mainstream summary of these meanings:<itemizedlist><listitem><para>A Note
is for information that should be heeded by all readers.</para>
</listitem><listitem><para>An Important element is a variation on Note.</para>
</listitem><listitem><para>A Caution is for information regarding possible
data loss or software damage.</para>
</listitem><listitem><para>A Warning is for information regarding possible
hardware damage or injury to life or limb.</para>
</listitem></itemizedlist></para>
<para>DocBook does not have an element for Danger, which some hardware and
manufacturing manuals require, but which is uncommon in software documentation.
</para>
<graphic entityref="admons-tree"></graphic>
<para>All the admonition elements contain an optional Title and one or more
object-level elements from the <sgmltag class="paramentity">admon.mix</sgmltag>
mixture. If no Title is supplied a title should be generated by formatting
applications.</para>
<graphic entityref="sidebar-tree"></graphic>
<para>Sidebar contains an optional Title and TitleAbbrev, and any number of
object-level elements from the <sgmltag class="paramentity">sidebar.mix</sgmltag>
mixture.</para>
</sect1>
<sect1>
<title>Lists, MsgSets, and Procedures</title>
<para>DocBook offers many elements for marking up sets of related information.
The more complex of these elements resemble specialized tables (or, seen another
way, database records) and may even be capable of being formatted as tables. 
</para>
<para>There are several ways to compare these elements: <itemizedlist><listitem>
<para>Number of parts in an item: <itemizedlist><listitem><para>ItemizedList,
OrderedList, CalloutList, SimpleList, and Procedure each contain a series
of unitary indivisible items (or steps).</para>
</listitem><listitem><para>GlossList and VariableList contain items that are
broken into two parts. (SegmentedList must have items that contain at least
two parts.)</para>
</listitem><listitem><para>MsgSet contains items that are broken into several
parts. (SegmentedList has items that may contain three or more parts.)</para>
</listitem></itemizedlist></para>
</listitem><listitem><para>Amount of content tagging: <itemizedlist><listitem>
<para>ItemizedList, OrderedList, SimpleList, and VariableList, imply nothing
about the meaning of their contents. SegmentedList contains sets of information
related in consistent ways across similarly positioned segments in neighboring
items, but the relation is not implied by the element.</para>
</listitem><listitem><para>Procedure contains ordered steps a user can perform
to achieve a certain outcome.</para>
</listitem><listitem><para>GlossList contains definitions for terms and concepts.
</para>
</listitem><listitem><para>CalloutList contains descriptions that are linked
to particular regions of graphics and code examples.</para>
</listitem><listitem><para>MsgSet contains highly stylized descriptions of
computer messages.</para>
</listitem></itemizedlist></para>
</listitem></itemizedlist></para>
<sect2>
<title>ItemizedList</title>
<graphic entityref="itemlist-tree"></graphic>
<para>ItemizedList contains one or more ListItem elements, which contain one
or more object-level elements from the <sgmltag class="paramentity">component.mix
</sgmltag> mixture. ItemizedList has an optional Spacing attribute, which
indicates the relative desired compactness of the list, and an options Mark
attribute, which is a keyword that indicates a prefix for the list (e.g. bullet,
dash, checkbox). Note that the list of keywords and defaults are implementation
specific.</para>
<para>ListItem contains one or more object-level elements from the <sgmltag
class="paramentity">component.mix</sgmltag> mixture. ListItem has an optional
Override attribute, which can be a character or string which is intended to
replace the default mark for an individual item only. The default for this
attribute is implementation specific.</para>
</sect2>
<sect2>
<title>OrderedList</title>
<graphic entityref="ordlist-tree"></graphic>
<para>OrderedList contains one or more ListItem elements. </para>
<para>OrderList has an optional Spacing attribute, which indicates the relative
desired compactness of the list, an optional Numeration attribute, which indicates
the style of the list numbering (defaults are implementation specific), an
Inheritnum attribute, which can be used to build lower-level numbers by prefixing
higher-level item numbers (for example, 1, 1.a, 1.b; the default is not to
inherit), and a Continuation attribute, which indicates whether numbers are
reset from previous lists, the default being to restart numbering with each
list.</para>
</sect2>
<sect2>
<title>CalloutList</title>
<para>CalloutList contains an optional Title and TitleAbbrev, and one or more
Callout elements, which contain one or more object-level elements from the <sgmltag
class="paramentity">component.mix</sgmltag> mixture.</para>
<para>Callout contains one or more object-level elements from the <sgmltag
class="paramentity">component.mix</sgmltag> mixture. Callout has a required
AreaRefs attribute, which links to one or more Areas or AreaSets that an individual
Callout describes.</para>
</sect2>
<sect2>
<title>SimpleList</title>
<graphic entityref="simplist-tree"></graphic>
<para>SimpleList contains one or more Member elements, which contain inline-level
text.</para>
<para>SimpleList has an optional Columns attribute, which indicates the number
of columns the list should be formatted into, and a Type attribute, which
indicates whether list items should be inline (separated by commas), vertical
(top to bottom in columns) or horizontal (left to right in columns).</para>
</sect2>
<sect2>
<title>VariableList</title>
<para>VariableList is a two-part list offering terms and their descriptions,
which may be presented as a table if desired.</para>
<graphic entityref="varlist-tree"></graphic>
<para>VariableList contains an optional Title and TitleAbbrev, and one or
more VarListEntry elements, which in turn contain one or more Term elements
and a ListItem.</para>
<para>VariableList has an optional TermLength attribute, which indicates,
in the same units that table ColWidth accepts, the approximate length of the
term content that should fit onto one line.</para>
</sect2>
<sect2>
<title>GlossList</title>
<graphic entityref="glossist-tree"></graphic>
<para>GlossList contains one or more GlossEntry elements.</para>
<para>GlossEntry contains, in fixed order, an optional Acronym, an optional
Abbrev, and either a GlossSee or one or more GlossDef elements. GlossEntry
has an optional SortAs attribute, which can contain an alternate sort string
to be used to create an alphabetized set of glossary entries.</para>
<para>GlossTerm contains one or more inline elements from the <sgmltag class="paramentity">
para.char.mix</sgmltag> mixture. GlossTerm has an optional BaseForm attribute,
which can contain the string corresponding to the term in a GlossEntry when
this GlossTerm is used in text in alternate form (for example, plural); it
can be used for linking to the entry in a Glossary or GlossList.</para>
<para>GlossSee contains one or more inline elements from the <sgmltag class="paramentity">
para.char.mix</sgmltag> mixture. GlossSee has an optional OtherTerm attribute,
which can be used to link to the GlossEntry of the real term to look up.</para>
<para>GlossDef contains one or more object-level elements from the <sgmltag
class="paramentity">gloss.def.mix</sgmltag> mixture, and any number of GlossSeeAlso
elements. GlossDef has an optional Subject attribute, which can contain one
or more subject area keywords for searching.</para>
<para>GlossSeeAlso contains one or more inline elements from the <sgmltag
class="paramentity">para.char.mix</sgmltag> mixture. GlossSeeAlso has an optional
OtherTerm attribute, which can be used to link to the GlossEntry of a related
term to look up.</para>
</sect2>
<sect2>
<title>SegmentedList</title>
<graphic entityref="seglist-tree"></graphic>
<para>SegmentedList contains an optional Title and TitleAbbrev, any number
of SegTitle elements, and one or more SegListItem elements which contain two
or more Seg elements. SegmentedList can be used to mark up sets of consistently
labeled information.</para>
</sect2>
<sect2>
<title>Procedure</title>
<graphic entityref="procedure-tree"></graphic>
<para>Procedure contains an optional Title and TitleAbbrev, any number of
object-level elements from the <sgmltag class="paramentity">component.mix
</sgmltag> mixture, and one or more Step elements.</para>
<para>Step contains an optional title, any number of object-level elements
from the <sgmltag class="paramentity">component.mix</sgmltag> mixture, an
optional Substeps element, which contains one or more Steps, and any number
of object-level elements from the <sgmltag class="paramentity">component.mix
</sgmltag> mixture. All of the contents of Step are optional, but when Step
is present it is required to have some content.</para>
<para>Steps and SubSteps have a Performance attribute to indicate whether
it is a requirement that the Step or SubSteps be performed. It defaults to
required.</para>
<para>SubSteps contains one or more Steps.</para>
</sect2>
<sect2>
<title>MsgSet</title>
<graphic entityref="msgset-tree"></graphic>
<para>MsgSet contains one or more MsgEntries.</para>
<para>MsgEntry contains in fixed order, one or more Msg, an optional MsgInfo,
and any number of MsgExplan elements. MsgExplan has the same model as MsgMain.
</para>
<para>MsgInfo contains a mixture of any number of MsgLevel, MsgOrig, and MsgAud,
in any order.</para>
<para>Msg contains in fixed order, an optional Title, MsgMain, and any number
of MsgSub or MsgRef elements in any order. MsgSub and MsgRef have the same
model as MsgMain.</para>
<para>MsgMain contains an optional title, and MsgText which contains any number
of object-level elements from the <sgmltag class="paramentity">component.mix
</sgmltag> mixture.</para>
<para>MsgExplan contains an optional Title, and one or more object-level elements
from the <sgmltag class="genentity">component.mix</sgmltag> mixture.</para>
</sect2>
</sect1>
<sect1>
<title>Callout Structures</title>
<comment>TBS: callout lists, *CO and CO elements, Areas, etc.</comment>
<para>AreaSpec contains a mixture of one or more Area or AreaSet elements,
in any order. AreaSpec has an optional Units attribute, which contains the
global unit of measure in which coordinates in this Spec are expressed; an
optional LineRange attribute, which indicates whole lines from startline to
endline in <quote>linespecific</quote> content; and an optional OtherUnits
attribute, which contains an implementation-specific keyword for the units
of measure used in this AreaSpec.</para>
<para>The Area element is declared to be <literal>EMPTY</literal>. It has
a Label attribute, a required Coords attribute, and an optional Units attribute,
which indicates the units of measure in which coordinates in this Area are
expressed; this attribute's value is inherited from AreaSet and AreaSpec if
not supplied.</para>
</sect1>
<sect1>
<title>Computer Examples</title>
<sect2>
<title>Formal and Informal Examples</title>
<graphic entityref="example-tree"></graphic>
<para>Example contains a Title, an optional TitleAbbrev, and one or more object-level
elements from the <sgmltag class="paramentity">example.mix</sgmltag> mixture.
Example contains an optional Label attribute.</para>
<graphic entityref="infexamp-tree"></graphic>
<para>InformalExample contains one or more object-level elements from the <sgmltag
class="paramentity">example.mix</sgmltag> mixture.</para>
</sect2>
<sect2>
<title>Program Listings</title>
<graphic entityref="proglisting-tree"></graphic>
<para>ProgramListing contains a mixture of LineAnnotations, CO elements, and
inline elements from the <sgmltag class="paramentity">para.char.mix</sgmltag>
mixture, in any order.</para>
<para>ProgramListing contains an optional Width attribute, which indicates
the number of columns in the longest line of the example for management of
wide output (e.g. 80).</para>
<para>ProgramListingCO contains AreaSpec, ProgramListing and any number of
CalloutList elements. AreaSpec contains a mixture of one or more Area and
AreaSet elements in any order. AreaSet contains one or more Area elements.
</para>
</sect2>
<sect2>
<title>LiteralLayout</title>
<graphic entityref="litlayout-tree"></graphic>
<para>LiteralLayout contains a one or more LineAnnotation elements and inline
elements from the <sgmltag class="paramentity">para.char.mix</sgmltag> mixture,
in any order. LiteralLayout has an optional Width attribute, which indicates
the number of columns in the longest line, for management of wide output,
and a Format attribute set to &ldquo;linespecific,&rdquo; indicating that
line breaks and leading white space are significant.</para>
</sect2>
<sect2>
<title>Screen Dialogues</title>
<graphic entityref="screen-tree"></graphic>
<para>Screen contains a mixture of one or more LineAnnotations, CO elements
and inline elements from the <sgmltag class="paramentity">para.char.mix</sgmltag>
mixture, in any order. Screen has an optional Width attribute, which indicates
the number of columns in the longest line, for management of wide output,
and a Format attribute set to &ldquo;linespecific,&rdquo; indicating that
line breaks and leading white space are significant.</para>
<para>ScreenCO contains AreaSpec, Screen and any number of CalloutList elements.
</para>
</sect2>
<sect2>
<title>ScreenShot</title>
<graphic entityref="screenshot-tree"></graphic>
<para>ScreenShot contains optional ScreenInfo, and either a Graphic or a GraphicCO.
</para>
</sect2>
</sect1>
<sect1>
<title>Figures and Graphics</title>
<sect2>
<title>Figure</title>
<graphic entityref="figure-tree"></graphic>
<para>Figure contains a Title, an Optional TitleAbbrev, and a mixture containing
one or more object-level elements from the <sgmltag class="paramentity">figure.mix
</sgmltag> mixture and object-level elements from the <sgmltag class="paramentity">
link.char.mix</sgmltag> mixture, in any order. Figure has an optional Float
attribute, which indicates whether the Figure is allowed to float in the output,
and an optional Label attribute.</para>
</sect2>
<sect2>
<title>Graphics</title>
<graphic entityref="graphic-tree"></graphic>
<para>The Graphic element offers three different ways to provide graphic data:<itemizedlist>
<listitem><para>It can have <literal>CDATA</literal> element content constituting
the data.</para>
</listitem><listitem><para>It can provide, in the optional Entityref attribute,
a reference to an entity containing the data.</para>
</listitem><listitem><para>It can provide, in the optional Fileref attribute,
a filename or pathname for the data.</para>
</listitem></itemizedlist></para>
<para>Graphic also has the optional attributes Format (for the notation of
the data) and SrcCredit.</para>
<para>GraphicCO contains AreaSpec, Graphic, and any number of CalloutList
elements.</para>
</sect2>
<sect2>
<title>InlineGraphic</title>
<graphic entityref="inlinegr-tree"></graphic>
<para>InlineGraphic contains CDATA. InlineGraphic has the following optional
attributes Entityref, Fileref, Format and SrcCredit.</para>
</sect2>
</sect1>
<sect1>
<title>Formal and Informal Tables</title>
<graphic entityref="table-tree"></graphic>
<para>Table contains a Title, an optional TitleAbbrev, and either one or more
graphic elements or one or more TGroup elements. Table has an optional Label
attribute.</para>
<graphic entityref="inftable-tree"></graphic>
<para>InformalTable contains either one or more graphic elements or one or
more TGroup elements.</para>
</sect1>
<sect1>
<title>Synopses</title>
<comment>TBS: how to choose between the synopsis elements.</comment>
<sect2>
<title>Synopsis</title>
<graphic entityref="synopsis-tree"></graphic>
<para>Synopsis contains a mixture of one or more LineAnnotation elements,
Graphic elements or inline objects from the <sgmltag class="paramentity">
para.char.mix</sgmltag> mixture, in any order. Synopsis has an optional Label
attribute.</para>
</sect2>
<sect2>
<title>CmdSynopsis</title>
<graphic entityref="cmdsynopsis-tree"></graphic>
<para>CmdSynopsis contains a mixture or one or more Command, Arg, Group, SBR,
in any order followed by any number of SynopFragment elements. CmdSynopsis
has a Sepchar attribute, which indicates the character that should be used
to separate command and all top-level arguments (an alternative value might
be <sgmltag class="attvalue">&amp;Delta;</sgmltag>), and an optional Label
attribute.</para>
<para>SynopFragment contains a mixture of any number of Arg or Group elements
in any order. SynopFragment has a required Linkend attribute to link to related
information.</para>
<para>Arg contains a mixture of one or more Arg, Group, Option, Replaceable,
SynopFragmentRef, SBR, and <literal>#PCDATA</literal> in any order. Arg has
a Choice attribute which indicates whether an argument must be supplied (this
default is optional); and a Rep attribute, which indicates whether the argument
is repeatable (this default is Norepeat).</para>
<para>Group contains a mixture of one or more Arg, Group, Option, Replaceable,
SynopFragment, SynopFragmentRef, and SBR elements, in any order. Group has
a Choice attribute, which indicates whether an argument must be supplied (this
default is optional); and a Rep attribute, which indicates whether the argument
is repeatable (this default is Norepeat).</para>
<para>SynopFragmentRef contains <literal>RCDATA</literal> and has a required
Linkend attribute to link to related information.</para>
</sect2>
<sect2>
<title>FuncSynopsis</title>
<graphic entityref="funcsynopsis-tree"></graphic>
<para>FuncSynopsis contains an optional FuncSynopsisInfo and either one or
more FuncPrototype elements or a repeatable block containing a FuncDef and
Void, or a FuncDef and VarArgs, or a FuncDef and a series of ParamDef elements.
FuncSynopsis has an optional Label attribute.</para>
<para>FuncSynopsisInfo contains a mixture or any number of LineAnnotation
and inline elements from the <sgmltag class="paramentity">computer.char.mix
</sgmltag> mixture, in any order. FuncSynopsisInfo has a Format attribute
set to &ldquo;linespecific,&rdquo; indicating that line breaks and leading
white space are significant.</para>
<para>FuncDef contains a mixture of any number of Replaceable, Function, and <literal>
#PCDATA</literal> in any order.</para>
<para>ParamDef contains a mixture of any number of Replaceable, Parameter,
FuncParams, and <literal>#PCDATA</literal>, in any order.</para>
<para>FuncPrototype contains the same markup as FuncDef and ParamDef. It provides
a wrapper element for this markup.</para>
</sect2>
</sect1>
<sect1>
<title>Formal, Informal, and Inline Equations</title>
<graphic entityref="equation-tree"></graphic>
<para>Equation contains an optional Title and TitleAbbrev, and either an InformalEquation
or one or more graphic elements. Equation has an optional Label attribute.
</para>
<graphic entityref="infeqn-tree"></graphic>
<para>InformalEquation contains one or more graphic elements.</para>
<graphic entityref="inlineqn-tree"></graphic>
<para>InlineEquation contains one or more graphic elements.</para>
</sect1>
</chapter>