[Prev] [Next]

2.4 Lists, MsgSets, and Procedures

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.

There are several ways to compare these elements:

• Number of parts in an item:
  • ItemizedList, OrderedList, CalloutList, SimpleList, and Procedure each contain a series of unitary indivisible items (or steps).

  • GlossList and VariableList contain items that are broken into two parts. (SegmentedList must have items that contain at least two parts.)

  • MsgSet contains items that are broken into several parts. (SegmentedList has items that may contain three or more parts.)

• Amount of content tagging:
  • 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.

  • Procedure contains ordered steps a user can perform to achieve a certain outcome.

  • GlossList contains definitions for terms and concepts.

  • CalloutList contains descriptions that are linked to particular regions of graphics and code examples.

  • MsgSet contains highly stylized descriptions of computer messages.

ItemizedList

ItemizedList contains one or more ListItem elements, which contain one or more object-level elements from the %component.mix; 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.

ListItem contains one or more object-level elements from the %component.mix; 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.

OrderedList

OrderedList contains one or more ListItem elements.

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.

CalloutList

CalloutList contains an optional Title and TitleAbbrev, and one or more Callout elements, which contain one or more object-level elements from the %component.mix; mixture.

Callout contains one or more object-level elements from the %component.mix; mixture. Callout has a required AreaRefs attribute, which links to one or more Areas or AreaSets that an individual Callout describes.

SimpleList

SimpleList contains one or more Member elements, which contain inline-level text.

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).

VariableList

VariableList is a two-part list offering terms and their descriptions, which may be presented as a table if desired.

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.

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.

GlossList

GlossList contains one or more GlossEntry elements.

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.

GlossTerm contains one or more inline elements from the %para.char.mix; 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.

GlossSee contains one or more inline elements from the %para.char.mix; mixture. GlossSee has an optional OtherTerm attribute, which can be used to link to the GlossEntry of the real term to look up.

GlossDef contains one or more object-level elements from the %gloss.def.mix; mixture, and any number of GlossSeeAlso elements. GlossDef has an optional Subject attribute, which can contain one or more subject area keywords for searching.

GlossSeeAlso contains one or more inline elements from the %para.char.mix; mixture. GlossSeeAlso has an optional OtherTerm attribute, which can be used to link to the GlossEntry of a related term to look up.

SegmentedList

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.

Procedure

Procedure contains an optional Title and TitleAbbrev, any number of object-level elements from the %component.mix; mixture, and one or more Step elements.

Step contains an optional title, any number of object-level elements from the %component.mix; mixture, an optional Substeps element, which contains one or more Steps, and any number of object-level elements from the %component.mix; mixture. All of the contents of Step are optional, but when Step is present it is required to have some content.

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.

SubSteps contains one or more Steps.

MsgSet

MsgSet contains one or more MsgEntries.

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.

MsgInfo contains a mixture of any number of MsgLevel, MsgOrig, and MsgAud, in any order.

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.

MsgMain contains an optional title, and MsgText which contains any number of object-level elements from the %component.mix; mixture.

MsgExplan contains an optional Title, and one or more object-level elements from the &component.mix; mixture.

[Prev] Admonitions and Sidebars
[Next] Callout Structures
[User's Guide Home] [Davenport Group Home]