Creating DITA maps using outliners

As long as you have a browser, The Cloud is your friend. I’ve previously described the potential role of OPML-based outlining tools for DITA map editing in a browser, but a recent DITA Chicks post by Karen Lowe on creating DITA maps using spreadsheets got me to wondering, “If the only tool I had was a web-based outlining tool, what could I do with it?”

The only other requirement for this exercise is a locally installed version of DITA Open Toolkit, mainly because it contains the Saxon transform engine needed for our small XSLT converter.  Just navigate to it and double click on the startcmd.bat file to open up a ready-to-go transform environment that we’ll use in a few minutes.

A popular task-planning tool for browsers is an outliner called CheckVist (just think of the V as a slanted L to get “checklist”). This task planner has quite a bit in common with the goals of the IBM Information Architecture Workbench (formerly Task Modeler) since the idea is to enable easy organization of intended workflows. We just have to squint a bit while editing (no worse than using a spreadsheet, believe me!) and run a transform to get a valid DITA map as a result.

I had a CheckVist account already (I use it for drafting presentations–it’s great for that job!), so I started by writing a small outline:

To create hrefs, I used the annotation control, typing “nn” on a selected line, to open a nested input window where I pasted URLs for pre-existing targets. Other list editors might allow you to insert an xmlURL attribute directly, which simplifies the directness of the transform. I used the Shift/Tab arrow controls to move lines and indentation until I had the organization I wanted. With the three “linked” sub-bullets added, my outline was looking like this:

Next, I saved my work as an OPML file using the export > OPML, which displays to the browser screen, from which you do a Ctrl-U to view the OPML source and then Ctrl-S to save it wherever you want under any name. I chose to save this stream in my DITA-OT directory as opml_Test_DITA_Map.xml.

Next I wrote a transform to rename the obviously equivalent DITA map elements and modify the attributes so that notes became hrefs for each parent outline, etc.. The XSLT style sheet looks like this:

Finally, I ran the Java command that applies the style sheet to the OPML file I had saved (both files are in an attachment to this post):

C:\DITA-OT1.5.2\opml>java net.sf.saxon.Transform -s:opml_Test_DITA_map.xml
-xsl:opml2map.xsl -o:my_test.ditamap

The resulting output, my_test.ditamap, is a valid DITA map that loads into a DITA editor where you can finish generating topics from the hrefs. It is certainly possible to modify the style sheet with the xsl:result-document directive to generate those stub files at transform time, but that is an exercise left to the reader.

So here is my outline, opml_Test_DITA_map.xml, as exported from a browser:

And the resulting DITA map after transformation:

And that map in an expeDITA collaboration tool view, ready for adding topics:

The process demonstrates to my liking the versatility of outliners for creating DITA map structures even when my regular DITA editor is not at hand. Cost: free plus a an evening of my time, including this write-up. Satisfaction: like telling a good pun. Utility: a good server-side project for wrapping in a simple GUI so that even the transforms happen In The Cloud!

Resources: opml sample archive (unzip into DITA-OT root directory; creates /opml subdirectory)

This entry was posted in DITA adoption, map editing, Uncategorized, XML and tagged , , , . Bookmark the permalink.

4 Responses to Creating DITA maps using outliners

  1. XML Editor says:

    you can actually significantly speed up your DITA developing with specific software, although I guess that kind of takes the fun and science out of it.

  2. Don says:

    So true, but you are right–the point was to see what could be done in the absence of such tools. Part of the perception of DITA’s complexity lies in the assumption that it can only be used with specific software. The posts by Karen and myself simply point out that the standard rules don’t always apply!

  3. Lu Hall says:

    Very cool Don. Thanks for sharing this. I agree, the perception that “DITA is hard” is an impediment to DITA adoption by a wider business base. We need more and better tools to support the standard and augment what the OT does. Your post (and Karen’s) prove that these tools don’t necessarily need to be super sophisticated or expensive.

  4. Mark Poston says:

    Very interesting Don. Thanks very much for sharing this.
    I too have been using OPML for a while now to create DITA maps and also DITA stub files.
    Having previously used my own XSLTs I now use the OPML transforms in the DITA for Publishers project. These are intended to create DITA subject schemes but were easy to adapt to create the DITA maps and topics for my purposes – primarily to create test DITA content.
    I use OmniOutliner on Mac to create OPML and also add further columns into my documents for other important metadata that gets incorporated into the content (including topic type). A node’s text in the OPML is sometimes used as the topic’s content. This is similar to what IBM’s Workbench does and does the job nicely for my work.

Comments are closed.