DITA uses the <title/> element for maps, topics, sections, examples, tables, and figures. (Among others; check the spec for the full glory of the title element.)
This is completely logical from a semantic tagging perspective. A title goes right on being a descriptive heading for a content grouping no matter what content grouping you're describing. During a transition to topic-based authoring with DITA, though, this may not seem entirely logical to the writing team.
Titles are Labels, Not Structure
Titles are not part of the main content tree structure represented by your XML document. They're in the XML document's tree structure, they have to be by the inflexible rules of XML. But a title element's limited descendants do not include the content of the thing for which they provide the descriptive heading, or indeed anything but the content of descriptive heading itself.
This means that you cannot follow the titles through the XML structure; they are labels stuck off to the side. They might not be there at all. (Even in a topic, titles are optional. You're going to have an interesting time with a CMS and displaying many title-less DITA topics, but you might think the interesting time is worth it.)
Structure is things like
- the composition of component maps into your main content deliverable map
- the sections of a topic
- the semantic labelling of some content inside a topic as a figure
- the nested group of topic reference elements in a map
Which is where the trouble with the "but is this an H2 or an H3?" question starts. (As you're transitioning to DITA, someone on your writing team is going to ask a question like that.)
In a desktop publishing application, heading levels are structure. The content is fundamentally flat, a continuous stream of characters. Structure is expressed through a change of formatting. In XML, structure must be expressed through the tree structure of the XML document; this is due to the rules of XML. Semantic structure can be expressed in other ways, but DITA uses strictly the XML tree structure.
In DITA XML structural terms, the title elements are descriptive labels for the other children of the title's parent node. It doesn't matter if that node is a figure or a bookmap; the title is a descriptive label for the other kids. (The title element itself has to be a child node of something by XML's inflexible rules. The title element is the child node of the node that's the parent of everything it labels.)
This is why using <title/> for everything that needs a descriptive heading works; the structure is already there in the XML tree, and all the processing needs from a human is the natural language label for this node of the tree.
Mistrust Of Automation
Any kind of authoring with DITA only works if the output generation works. You can do all the semantic tagging in XML you like, but if you can't get from the XML to what your customers expect as a delivery, the process as a whole is going to fail.
Oddly enough, the chances of the members of your writing team being filled with hope and confidence about any kind of software aren't good. There are a bunch of potential reasons for that, and I'm only going to go into one of them.
Unless (a very large unless) you're transitioning to XML from SGML, you and your writing team have never used anything primarily designed to create and maintain structure in your content. Whatever it is, it will have been designed to label text—strictly, some sequence of character data—with presentation information (font, font size, font style, and so on), possibly in clever ways (FrameMaker's concept of a frame as a container from which formatting properties derive, for instance). Even something like Structured Framemaker retains both the tight link between content and format and the concept of a formatting over-ride, so you're not seeing true form/content separation. Without true form/content separation, you're also seeing software that has to deal with an effectively arbitrary range of special cases, which makes it very hard to produce and fully test that software.
Once you have both XML and[1] true form/content separation in your content, the number of special cases the software has to deal with drops enormously; it no longer has to find a way to allow for "this one specific title element is different from all other title elements", and can proceed on the basis of "what to do with this title element is defined by its parent element".
As a result, output processing that really does Just Work is readily achieved using XSLT. It take awhile to believe this, and it might take your XSLT programmer a little while to achieve this, but it is straightforwardly possible.[2]
There may be minor issues with use of titles in figures and tables, where it's perfectly straightforward to put the title after the image or table in the delivered document, despite the title occurring before anything else (it's the first child element of the node it labels; this is a good convention!) in the DITA content. Practice will allow adjustment to this.
But is it an H2 or an H3?
This is usually asked about topic titles. The answer is "it depends on where it is in the structure of whatever you're processing into a delivered document".
A topic can be referenced by many different maps; it can be referenced more than once by the same map. It can also be processed directly, as itself. The heading level of a particular title element in the output depends on the position of the content node labeled by that title element in the DITA XML structure that's being processed into a delivered document.
Which is the same as saying that any individual topic title element could, depending on its position in the structure defined by a map, provide a title at any heading level in the eventual content delivered.[3].
This understanding of the topic as the individual brick from which the house of the content delivery is built can be—I've seen it split about fifty/fifty in a writing team—the really tough mental transition point. It's a topic; it goes somewhere in a content delivery. You don't know what the output processing is eventually going to do to the title elements in this, or any other topic. You don't have to worry about heading levels; just structure.
But What About Chapters?
In a regular DITA map, a chapter is a formatting convention, presumably a special case in the output processing that says "this is the first reference down from the root in the map, it must be a chapter". In a bookmap, chapters are an explict reference using the <chapter/> element or <topicref/> children of a <chapter/> element.
Keep in mind that even when formally semantically defined chapters exist, chapter handling may vary between output types. HTML output is unlikely to have a concept of chapter at all, but you might process bookmaps to HTML. PDF outputs may have a formal, starts-on-a-recto, chapter title halfway down the page, chapter, or they may do something like continuous text with outline numbers to distinguish where you are in the organization. The same map, depending on output processing, may be produced using either or both of these conventions, or any others that you may have. Output processing is not compelled to treat chapters in any particular way; chapter handling depends on what you have locally created as your output processing.
There's Stuff Between a Chapter and a Topic!
Sure, but that stuff is going to have <title/> elements, too.
Whether you provide titles for topic grouping through topic nesting, component maps that are assembled into your top-level content deliverable map, or some form of specialization, if you're using DITA, you have a tree representation of your content built into the XML. You can't hope to avoid this. You really shouldn't be trying to avoid that.
Given that DITA XML tree structure, the title element is the natural way to present a descriptive heading. Anything that would appear in a complete table of contents is going to be the title element child of a node in the XML structure of your DITA map.
Summary
DITA title elementa are descriptive labels for nodes in the content tree, irrespective of the amount of content tree below the labeled node.
The output processing can effectively and automatically determine how to represent each title.
This is a signficiant change from narrative authoring in a desk top publishing application, where heading levels function to demarcate structural divisions in the document. In DITA, a title becomes strictly a descriptive heading, and does not get overloaded as a structure representation. This simplifies the writing process; you'll never have to go and change an H2 to an H3 because you moved a block of content.
[1] This is a mighty and; it's perfectly possible (as both Open Office and recent versions of Word do) to use XML to represent the content in a desktop publishing application.
[2] There are of course other options for processing XML into delivered content. XSLT has the advantage of being designed to solve this specific problem of XML tree transformation.
[3] DITA itself allows arbitrarily deep nesting; you'll have to make a style decision about how much depth you want your output processing to support, and how you'll have the output processing respond to overly deep nesting. Because you can nest maps in maps, it's not straightforward to test for nesting depth before output processing.
[4] You can have multiple title elements in a single section element; this is entirely valid according to the DITA specification. It will also make a serious mess of your outline numbering, if outline numbering is involved. This is a good place for a Schematron rule.
Posts
No comments:
Post a Comment