Core BusDocs Topic
The following is a list of the elements that exist in the base topic with a discussion of their relevance to the aggregated business document requirements. The intention is to constrain the BusDocs topic and encourage implementers to edit the constraints to restore elements that are required by a specific implementation.The Core BusDocs Topic is sufficient to author all of the documents represented in the Benchmark Document Set.
In terms of adoption, we would suggest that organizations that are new to DITA will have an easier time identifying additional features they might need beyond the Core BusDocs Topic, than they would have identifying what to remove from the full Topic specification.
Table 3: Reconciliation of Topic Elements
title( text data orboolean or
keyword or
ph or
b or i or u or
sup or sub or
tt or
q or
term or
tm or
state or
data or
data-about or
foreign or
unknown or
image) (any number)
then / Title is required for all sections in an aggregated business document. While this may not always appear to be the case, significant review of source documents has led the subcommittee to this conclusion.
It would be highly unusual for aggregated business document section titles to use other than: b, i, u, sup, sub.tm, and q. The remaining elements are constrained by the BusDocs topic constraint file.
titlealtsoptional( (navtitle) (optional) then (searchtitle) (optional) )
then / It would be highly unusual for aggregated business documents to use titlealt, and it is constrained by the BusDocs topic constraint file.
shortdesc( text data or
boolean or
keyword or
ph or
b or i or u or
sup or sub or
tt or
q or
term or
tm or
state or
data or
data-about or
foreign or
unknown or
image or
draft-comment) (any number)
or / Short description is an element of a limited number of aggregated business document types. It is constrained by the BusDocs topic constraint file but should be restored if used for specific information types in an implementation.
abstractoptional ( text data or
dl or
fig or
imagemap or
image or
lines or
lq or
note or
hazardstatement or
object or
ol or
p or
pre or
simpletable or
sl or
table or
ul or
boolean or
cite or
keyword or
ph or
b or i or u or
sup or sub or
tt or
q or
term or
tm or
xref or
state or
data or
data-about or
foreign or
unknown or
shortdesc or
draft-comment or
fn or
indextermref or
indexterm or
required-cleanup) (any number)
then / In the context of an aggregated business document, it is more common for abstract to be modeled by topic than by an element within topic. It is constrained by the BusDocs topic constraint file.
prologoptional ( (author) (any number) then (source) (optional) then (publisher) (optional) then (copyright) (any number) then (critdates) (optional) then (permissions) (optional) then (metadata) (any number) then (resourceid) (any number) then (data or
data-about or
foreign or
unknown) (any number) )
then / A specialization of prolog will be necessary for a number of aggregated business information types. It is constrained by the BusDocs topic constraint file but should be restored if used for specific information types in an implementation.
bodyoptional(dl or
figor
imagemap (utils domain) or
image or
lines or
lq or
note or
hazardstatement (haz. domain) or
object or
ol or
p or
pre or
simpletable or
sl or
table or
ul or
data or
data-about or
draft-comment or
foreign or
unknown or
required-cleanup or
bodydiv or
example or
section) (any number)
then / The Busdocs body is highly constrained to provide the base set of necessary components with minimal ambiguity. It is expected that general information types suggested by the BusDocs subcommittee as well as information types built on top of aggregated authoring by other subcommittees will restore and specialize individual elements to expand this list as required.
Specific rationale for constraint of elements is given in Table 4.
fig or
image or
ol or
rul or
p or
table(any number)
related-linksoptional (link or
linklist or
linkpool) (any number)
then / It would be unusual for aggregated business documents to use related-links, and it is constrained by the BusDocs topic constraint file.
topicany number / As described in this document.
Topic
Components / Description / General
BusDoc
requirement / Niche
BusDoc
requirement. Unconstrain or specialize for Info Types as needed / Belongs to a Domain that is not required for BusDoc authors / Oriented to Layout / IT /
Publications.
No identified use casefor BusDoc authors / Oriented to Tech Pubs.
No identified use case for BusDoc authors / Possible BusDocs use case, but introduces
ambiguity
dl or / A definition list (<dl>) is a list of terms and corresponding definitions. / X
fig or / The figure (<fig>) element is a display context (sometimes called an "exhibit") with an optional title for a wide variety of content. Most commonly, the figure element contains an image element (a graphic or artwork), but it can contain several kinds of text objects as well. A title is placed inside the figure element to provide a caption that describes the content. / X
imagemap or / The imagemap element supports the basic functionality of the HTML "client-side" image map markup. Imagemap allows you to designate a linkable area or region over an image, allowing a link in that region to display another topic. / X
image or / Include artwork or images in a DITA topic by using the <image> element. The <image> element has optional attributes that indicate whether the placement of the included graphic or artwork should be inline (like a formula or character set that is not supported natively) or on a separate line for a larger image. / X
lines or / The <lines> element may be used to represent dialogs or text fragments where line breaks are significant. The <lines> element is similar to <pre> in that hard line breaks are preserved, but the font style is not set to monospace, and extra spaces inside the lines are not preserved. / X
lq or / The long quote (<lq>) element indicates content quoted from another source. Use the quote element <q> for short, inline quotations, and long quote <lq> for quotations that are too long for inline use, following normal guidelines for quoting other sources. / X
note or / A <note> element contains information, differentiated from the main text, which expands on or calls attention to a particular point. / X
hazardstatement or / The <hazardstatement> element contains hazard warning information. / X
object or / DITA's <object> element corresponds to the HTML <object> element, and its attributes' semantics derive from their HTML definitions. The <object> element allows authors to include animated images, applets, plug-ins, ActiveX controls, video clips, and other multimedia objects in a topic. / X
ol or / An ordered list (<ol>) is a list of items sorted by sequence or order of importance. / X
p or / A paragraph element (<p>) is a block of text containing a single main idea. / X
pre or / The preformatted element (<pre>) preserves line breaks and spaces entered manually by the author in the content of the element, and also presents the content in a monospaced type font (depending on your output formatting processor). / X
simpletable or / The <simpletable> element is used for tables that are regular in structure and do not need a caption. Choose the simple table element when you want to show information in regular rows and columns. For example, multi-column tabular data such as phone directory listings or parts lists are good candidates for simpletable. / X / X
sl or / The <sl> element contains a simple list of items of short, phrase-like content, such as a list of materials in a kit or package. / X / X
table or / The <table> element organizes arbitrarily complex relationships of tabular information. This standard table markup allows column or row spanning and table captions or descriptions. An optional title allowed inside the table element provides a caption to describe the table.
The DITA table is based on the OASIS Exchange Table Model, augmented with DITA attributes that enable it for specialization, conref, and other DITA processing. In addition, the table includes a desc element, which enables table description that is parallel with figure description. / X
ul or / In an unordered list (<ul>), the order of the list items is not significant. List items are typically styled on output with a "bullet" character, depending on nesting level. / X
data or / The <data> element represents a property within a DITA topic or map. While the <data> element can be used directly to capture properties, it is particularly useful as a basis for specialization. / X
data-about or / The <data-about> element identifies the subject of a property when the subject isn't associated with the context in which the property is specified. The property itself is expressed by the <data> element. The <data-about> element handles exception cases where a property must be expressed somewhere other than inside the actual subject of the property. The <data-about> element is particularly useful as a basis for specialization in combination with the <data> element. / X
draft-comment or / The <draft-comment> element is designed to facilitate review and discussion of topic contents within the marked-up content. Use the <draft-comment> element to ask a question or to make a comment that you want others to review. To indicate the source of the draft comment or the status of the comment, use the author, time or disposition attributes. / X
foreign or / The <foreign> element allows the introduction of non-DITA content, for example, MathML, SVG, or Rich Text Format (RTF). The <foreign> element or a specialization may contain more than one type of non-DITA content or a mix of DITA and non-DITA content. Specialization of the <foreign> element generally is implemented as a domain, but architects looking for more control over the content may implement foreign vocabularies as structural specializations. / X
unknown or / The <unknown> element is an open extension that allows information architects to incorporate xml fragments that do not necessarily fit into an existing DITA use case. / X
required-cleanup or / required-cleanup> element is used as a placeholder for migrated elements that cannot be appropriately tagged without manual intervention. As the element name implies, the intent for authors is to clean up the contained material and eventually remove the <required-cleanup> element. Authors should not insert this element into documents. / X
bodydiv or / The <bodydiv> element is used to contain informal blocks of information within the body of a topic. The bodydiv element is specifically designed to be a grouping element, without any explicit semantics, other than to organize subsets of content into logical groups that are not intended or should not be contained as a topic. As such, it does not contain an explicit title to avoid enabling the creation of deeply nested content that would otherwise be written as separate topics. Content that requires a title should use a section element or a nested topic. / X
example or / The <example> element is a section with the specific role of containing examples that illustrate or support the current topic. The <example> element has the same content model as <section>. / X / X
sectionany number / The <section> element represents an organizational division in a topic. Sections are used to organize subsets of information that are directly related to the topic. Multiple sections within a single topic do not represent a hierarchy, but rather peer divisions of that topic. Sections cannot be nested. A section may have an optional title. / X
Table 4: Topic Body Elements and their Relationship to Aggregated Business Document Authoring
Nesting of Common Body Elements
DITA provides authors with the ability to nest components in such a way that a “child” component is contained within a “parent” component. For reasons that are discussed below, the subcommittee suggests that the business authors targeted for this solution will have limited experience thinking about document content in the manner shown in the following examples:
Example 1: a list that is a child of a paragraph
<p>The maximum allowable indirect cost is computed based on:
<ol>
<li>the total Grant Amount</li>
<li>the total Indirect Costs</li>
<li>the Indirect Cost Rate</li>
</ol
</p>
Example 2: a paragraph that is a child of a list item.
<li> Find text for this illustration that takes this list item beyond one paragraph.
<p> This will be the second paragraph that continues . </p>
</li>
There are several reasons why this type of nested structure might be used in an XML document. Perhaps the most significant one from an author’s perspective is the assurance that the child component will always accompany its parent when the latter is published, reused, cited, etc. Looking at the examples again, it is clear that neither of these parents would make sense without the child.
The entire subject of “keeping content together” when it is published or reused is likely to be a new concept to business document authors who have traditionally delivered their content on paper or monolithic web pages. Neither of these delivery mechanisms allows components to be separated, and therefore the distinction of parent child is not relevant. When it comes to reuse with these delivery mechanisms, there is no control over what can be copied from one document to another when using a common word processor, so once again the distinction loses some relevance.
A review of business documents shows that their authors are familiar with indenting content, which can in some cases be interpreted as an indication of hierarchical relationship. However to assume that all uses of indenting in business documents implies the author’s conscious “mark-up” of parent-child relationships is not consistent with the kind of aesthetic use of formatting that is often found.
The specific level of nesting that should be provided in an aggregated authoring solution will vary by implementation. In general, the subcommittee recommends that there be no more opportunity to nest components than is required by the content model of each information type that is to be implemented. There are three reasons for this:
•Aggregated business documents already incorporate a significant hierarchical structure that is not accounted for in standalone topics. Since indenting is often used when authoring or presenting content made up of nested sections, this presents a physical limit to the amount of body component nesting that can be accommodated in many authoring and presentation environments.
•Based on DTD and XML schema specification, it is not possible to limit the amount of recursion of nested elements that can occur once two elements are nested within each other. For example, paragraph within list item and list item within paragraph, creates an infinite recursion. This is true for the majority of elements within the topic body.
•The continued appearance of nested elements in an insertables list (a UI component implemented in many XML authoring environments) adds significant and unnecessary complexity for an aggregated business document author if the nested elements continue to appear at levels where they are not required.
For this reason, the Core BusDocs Topic severely limits nesting to less than what we believe will be required for many document types. This is to create an opportunity for implementers to avoid infinite recursion by using semantic element names for nested elements if they choose to do so.
The following nesting is supported in the Core BusDocs Topic:
Paragraph / Ordered List or Unordered List/List Item / Figure / Image / Table/Tgroup/Row/Entryfig / fig / fig
image / image / image / image
ol / ol / ol
p
ul / ul / ul