DITA maps and OPML revisited, part 2

Previously, I introduced some background behind various types outlining software; in this post I’ll explore the relationship between DITA maps and OPML lists, and look at how OPML might be used in in-browser DITA applications.

So what does OPML look like? Here is a small sample that provides a list of various content types on the web, which can be thought of as DITA topics, separate DITA maps, or lists of search results.

<?xml version="1.0" encoding="utf-8" ?>
<opml version="2.0">
_<head> 1
__<title>OPML Links</title> 2
__<dateCreated>Sat, 26 Sep 2009 13:00:00 GMT</dateCreated>
__<dateModified>Sat, 26 Sep 2009 13:00:00 GMT</dateModified>
__<ownerName>Geoff Taylor</ownerName>
__<ownerId>http://www.opinionatedgeek.com/Blog/</ownerId>
__<docs>http://www.opml.org/spec2</docs>
_</head>
_<body> 3
__<outline text="Useful OPML Links"> 4
___<outline text="OPML Validator" type="link" url="http://validator.opml.org/" />
___<outline text="OPML Icon Project" type="link" url="http://www.opmlicons.com/" />
___<outline text="OPML Version 1.0 Spec" type="link" url="http://www.opml.org/spec" />
___<outline text="OPML Version 2.0 Spec" type="link" url="http://www.opml.org/spec2" />
__</outline>
__<outline text="Samples"> 5
___<outline text="Sample Play List" type="include" ___url="http://static.userland.com/gems/radiodiscuss/playlist.opml" />
___<outline text="Sample Specification" type="include" ___url="http://static.userland.com/gems/radiodiscuss/specification.opml" />
___<outline text="Sample Presentation" type="include" ___url="http://static.userland.com/gems/radiodiscuss/presentation.opml" />
___<outline text="Sample Directory" type="include" ___url="http://radio.weblogs.com/0001000/gems/publications.opml" />
___<outline text="Sample Feed List" type="include" ___url="http://www.scripting.com/feeds/top100.opml" />
__</outline>
_</body>
</opml>

    1 OPML requires a head, which is transformationally equivalent to a DITA map’s topicmeta element at the map level. 

    2 The nested title of OPML is directly equivalent to the first child title of a DITA map.

    3 OPML requires a body. The head and body elements are effectively syntactic sugar that can be inferred in transforms between DITA map and OPML.

    4 The OPML outline elements with type=”link” are equivalent to topicref elements in a DITA map. When used as text only, they are directly equivalent to topichead elements in DITA. This first group wraps a set of links to home pages, so they are effectively equivalent to topicref links to discrete topics referenced by URL. Relative file links are supported as well, which is common DITA practice in topicrefs.

    5 The outline elements in this titled set refer to other OPML lists. Thus they are directly equivalent to DITA map references (where OPML’s type=”include” mimics the format=”ditamap” semantic in DITA maps). Moreover, some of these links could actually represent dynamic information such as the most current or most popular links at a site, thus representing query results.

Based on this analysis, it appears that OPML’s nested outline elements and general structure are transformationally equivalent to a DITA map’s nested topicref and topichead elements. A small rub is that there is no standard for the type enumerations or additional attribute names/values that particular applications might invent for their specific metadata.

Note that we did not cover anything equivalent to reltables or a good many standard DITA attributes. So OPML is not a complete stand-in for DITA maps. My original goal was to learn whether OPML and its tools could represent DITA maps on a wiki for non-tech writers. The good news is that OPML does seem well suited in this role to enable navigation that is live-editable in a collaborative environment.

But wait, why not revise the live editing code to enable direct editing of DITA map syntax instead? I tried just that, but upon thinking about supporting my own hacked code, I decided the long term investment was misplaced. Live outline editors do not work on the direct markup syntax, per se–they operate on HTML structures. The in-browser editing workflow requires using XSLT to convert source markup (whether @text or @navtitle) into a closest HTML equivalent so that it can be accessed by JavaScript in the HTML DOM. Given that most markup in both XML languages needs to be transformed into editable HTML anyway, support for the editor is likely to be better for the more common form of list used on the web: OPML.  And since it is very easy to convert OPML into DITA on demand, it makes better sense to use the more popular interfaces and tools of OPML in a wiki environment.

So just a note on OPML editors–most such tools were designed as desktop editors, not as in-browser tools. The editor that convinced me that OPML could be used as a handy navigator was a demo created by Joshua Allen (http://www.netcrucible.com/xslt/opml.html). It is not full featured, but it behaves like popular outlining tools such as CheckVist, being very easy to use. And the editing workflow is more reliable than the method used in expeDITA: converting the map to a list of HTML links, and praying that users don’t overwrite the hidden syntax that allows the lists to be reconverted back to DITA upon save.

And because of the close equivalence of OPML to DITA maps, I now know that I can use use any outliner using the type=”link” conventions to create structures that I can convert into DITA maps later on. How cool is that?

I hope this information helps other developers who are creating in-browser DITA applications to make use of the OPML functionality for DITA maps where appropropriate!

Resources:

  1. OPML and XSLT article.
  2. OPML 2.0 specification.
This entry was posted in DITA, expeDITA. Bookmark the permalink.

One Response to DITA maps and OPML revisited, part 2

  1. Pingback: Tweets that mention DITA maps and OPML revisited, part 2 | Learning by Wrote -- Topsy.com

Comments are closed.