Writing in DITA - Tips #4 to 10

A verbose version of these tips was published in the Mar-Apr 2010 issue of STC India's newsletter, INDUS, as DITA writing tips.

4. To conref dissimilar elements, wrap the source text in <ph>
5. To prevent all topics of a <reltable> row from linking back to each other, use the 'linking' attribute of <topicref;
6. To include pretty much anything in a <step>, insert an <info>
7. To preserve the formatting of a copy-pasted text snippet, use <pre>
8. To have topics show different titles in different scenarios, use <titlealts>
9. To caption images, use <fig> as container for <image>
10. To have a slightly longer <shortdesc>, put it in an <abstract>

To conref dissimilar elements, wrap the source text in <ph>

DITA is about content reuse - with a rider. Only like can call like. I cannot, for example, reuse a <step> as an <li> - if I want to reuse the text of a <step>, I can conref it only from another <step>. This becomes a bit of a hassle - say, I have written something in a <shortdesc> in a concept topic that makes perfect sense as the <context> of a task topic, how do I conref it? By using the <ph> tag.

To prevent all topics of a relationship table row from linking back to each other, use the 'linking' attribute of the <topicref> element

The relationship tables in DITA are an extremely useful tool for maintaining, at a single point, the linking between all topics in a book. Each row in the table represents a discrete relationship and all files in a row link back to each other. But sometimes I end up with more links than I really want. To prevent that, I qualify the <topicref> tags with either a sourceonly attribute or a targetonly attribute. When a <topicref> has a sourceonly attribute, a link is generated to the target topic only in the source topic; when it's targetonly, a link is generated to the source topic only in the target topic.

To include pretty much anything in a <step> tag, use an <info> tag

When describing procedures, sometimes it becomes necessary to include things such as pictures, code snippets, explanatory notes, and so on. But a <step> tag can contain only a <cmd> tag and then a bunch of other tags that are pretty useless for pictures, notes, and code. The workaround is to insert an <info> tag after the closing <cmd>; an <info> tag can contain pretty much anything.

To preserve the formatting of a copy-pasted text snippet, use <pre>

Because DITA is XML, anything enclosed within < > is interpreted as a tag. So how do I include, for example, a code snippet that contais angular brackets? I wrap the text in a <pre> tag, just like I'd have done if I were writing it in HTML.

To have the topic show different titles in different scenarios, use <titlealts>

I use <titlealts>, with which I can specify two additional titles: a <navtitle>, which shows up in the ToC pane, and a <searchtitle>, which shows up in the search results page. I make these two titles slightly more verbose than the actual page title, so that they make sense even when seen outside the context of the page content. In the absence of a <titlealts> tag, the title displayed in the ToC and in the search result page defaults to what's contained in the <title> tag.

To caption images, use <fig> as container for <image>

The easiest way to put an image in a topic is by using an <image> tag. But, according to the DITA language specification, an <image> tag cannot contain anything other than alt text. How do I caption my images? By wrapping the <image> tag in a <fig> tag, which can contain not only a <title> tag but a host of other useful ones such as <desc>, <note>, and <codeblock>.

To have a slightly longer <shortdesc>, put it in an <abstract>

The <shortdesc> element is what I use for writing the "click-through text" for the topic - the text that shows up in search results and in hovertext for links. Mostly, my short descriptions contain 2-3 sentences that sum up the topic. But sometimes, just sometimes, I feel the need to write a longer short description. I'd still like to retain the shorter short description as the "pull text", but what if I want to add another two sentences and want to have them all in that section itself - the first section on a page - instead of carrying the extra sentences over to the body of the topic (where they'll probably have to reside after a <prereq> and, thus, lose all sense of connect)? In such a case, I use an <abstract> tag