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?"
Don Daymigration, editingThe 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 theorganizationI 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)