Thursday, May 13, 2010

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.

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

Sunday, May 9, 2010

DITA 1.2 - New <task> elements

The DITA language specification v1.2 introduces two new task elements: <steps-informal> and <stepsection>.
The <steps-informal> element is for describing procedural information that is otherwise not normally described as a step. The <stepsection> is for giving explanatory information before a step. It is contained within the <steps> element and can be placed betweeen two <step> elements; the output of the content of a <stepsection> will not contain a bullet or a number.

When should I use the <steps-informal> and <stepsection> elements

<steps-informal>: The v1.2 language specifications haven't yet included an example of the <steps-informal> element so I am still a bit unclear about how and when to use it.
<stepsection>: If I am using DITA v1.1 and need to give some info before a step, the only way I could do that was insert an <info> in the previous step. With <stepsection>, this problem is resolved. Here's an example (taken from the v1.2 lang specs doc):
<steps>
  <step><cmd>Get out a bowl</cmd></step>
  <stepsection>The next two steps are very important!</stepsection>
  <step><cmd>Put on safety gloves</cmd></step>
  <step><cmd>Put on goggles</cmd></step>
  <step><cmd>Pour milk and cereal into the bowl</cmd></step>
</steps>

Related information

With v1.2, a <step> can have an <note> before the <cmd>.

  

Friday, May 7, 2010

DITA 1.2 - New <topic> elements

The DITA language specification v1.2 introduces two new topic elements: <bodydiv> and <sectiondiv>.
The <bodydiv> element is intended to be used as a grouping element for containing logical blocks of info that otherwise do not need either a title or a separate topic. It can be placed only within a <body> or within another <bodydiv>.
The <sectiondiv> element is similar to the <bodydiv> element except that it has more container elements - it can be placed within a <section>, <sectiondiv>, and a bunch of other tags depending upon the topic type.

Why and when should I use <bodydiv> and <sectiondiv>

If I want to reuse a whole group of info somewhere else, these two tags are handy. Not that such reuse couldn't have been done otherwise, but then, these tags can, for example, contain several <p> elements, some lists, some images...it's almost like being able to reuse an information chunk instead of individual tags. Without being actual formal topics, these tags behave like topics.

Related information

The <concept> topic type also has a new element in v1.2 that's similar to <bodydiv> and <sectiondiv>. It's called <conbodydiv>.

History of <topic> elements

Here's a list of the various topic elements from v 1.0 to 1.2:

DITA 1.0DITA 1.1DITA 1.2
dita--
topictopictopic
titletitletitle
titlealtstitlealtstitlealts
navtitlenavtitlenavtitle
searchtitlesearchtitlesearchtitle
-abstractabstract
shortdescshortdescshortdesc
bodybodybody
--bodydiv
sectionsectionsection
--sectiondiv
exampleexampleexample
related-linksrelated-linksrelated-links