Under the hood with the poor man's DITA editor

The expeDITA editor utilizes a freely available Rich Text component as the WYSIWYG editor. Given that most narrative content in DITA is exactly what you would compose with a standard Rich Text editor anyway, the match is remarkably good for most body content. The devil, of course, is in the details.

The expeDITA default editor support depends on a careful orchestration of transforms into "hinted HTML" for the editor, then back out into regular (type-validated) DITA.

Validation:

"Type validation" (loosely like type acceptance) means that the output transform relies on pull patterns to represent the main valid structures, mainly leaving only the content of blocks as normally push-based (fall-through) transforms. In this manner, the overall result is normally valid, and mixed content is most at risk of being invalid. Transforms can sometimes be tuned to head off persistent user patterns.

HTML components naturally offer far more "bad options" than desired, such as font size and color controls. Using the normal customization interfaces for the component, the "non-DITA" controls can be removed. In some cases, elements such as codeblock and lines can be represented as styles associated with the generic "div" element. In this fashion, DITA's heritage of elements based on HTML is actually used to advantage, and a surprising amount of DITA functionality can be enabled.

Maps:

The t2h (topic-to-html) "in" transform script handles the conversion of both map and topic content into HTML. Topicrefs have both a nesting and a linking semantic. Since no single HTML element has the same behavior, the hierarchy is represented using using lists, and the linking using the anchor tag. CSS styling creates "named fields" for handling the navtitle content as directly authorable content. List items with navtitle content but no links are implicitly equivalent to topicheads. The list item structure is fairly easy to cut and paste and shove around within the HTML editor. (Note--OPML list editors demonstrate an alternate way to edit maps, using Javascript controls to move elements up, down, in and out, hence with less potential "cut/paste" damage to the structures by users. We'll need some user testing to see which method is more popular and reliable.)

A separate h2m (html-to-map) transform converts map content back into DITA map syntax. The templates can't be part of the h2t (html-to-topic) transform due to fundamental difference in supported doctypes and overall logic.

DITA-specific features:

• Support for marking valid conref targets:
  • Can we adapt the Link menu to list viable targets as a pick list, to minimize file exploration?
• Support for marking for conditionality:
  • Best to do a focus group input session to understand the bare minimum requirements.
• Support for specializations in the editor:
  • For now, draw the line at DITA 1.1 topics. Even abstract throws a wrench in a free-form model.
• Support for entering complex required markup:
  • Task steps in particular (these are list items, and the user must know to insert a hinted [ph] as a manual step). A new button mapped to a custom function can be used to generate the complete step, with hinted text already in place. Same for linkable figures (the id and title need to be prompted) and other such multiple-step constructs as identified.

Architecture diagram:

The logic depicted shows a complete edit cycle (three state transitions) in one diagram. In short, DITA content is converted into hinted HTML for loading into the editor, and the saved stream is converted back into DITA. Through testing, I've learned that certain pre and post processing is necessary regardless of the component. In general, most components behave rather the same under the covers, but there are some browser-dependent differences in tagging (

b

vs

span/@style='font-weight:bold'

). And depending on the normalizer (which ensures a more or less "standard HTML"), various symbols and literal characters might need a final transposition. Not shown here is a bit of regex code that enables preservation of whitespace and other characters allowed in XML but not HTML. I worry more about corrupting Unicode codepoints in this path than markup validity itself as an issue.

All the user sees is a jump into editor mode and then back to viewing mode. If the view is kept inline (by keeping edit logic to a portion of the screen rather than replacing the view), then the state change can be done using the same HTML as is already painting the view (with the hinting added, of course).

And that is how DITA can be created and, to some extent, round-tripped with edits in a very basic browser environment.