Turning an HTML editor into a “poor man’s DITA” editor

XML editors generally require a great deal of programming investment to make them competitively featured for primary audiences of trained technical writers and professional communicators. HTML editors, on the other hand, are seemingly everywhere, if only they could somehow “do DITA.” I’ve been looking into ways to enable cheap editing capability in order to open up DITA authoring for user communities whose budgets and requirements are usually much more spare than for users of traditional XML editors. For open source and special interest communities, sometimes any cost can be a deal breaker.

It’s not that free and very capable DITA editors aren’t already available–these exist for desktop or Java environments.  But I was looking for something that would “just work” on a basic Web server/programming stack for ease of contribution and deployment. It is possible to write XML editors entirely in JavaScript to run on the browser, but the few that are open source either expose too much structure awareness to casual users, or are specific to particular browsers. In the last few years, however, a new option has become commonplace: so-called “rich text editors” that you find more and more in blogs and wikis. The trick is to wrap them somehow with a general, good enough, DITA capability.

In-browser editing capability was first introduced in the Internet Explorer 5 era via an attribute called contentEditable. When that attribute is enabled on an element, content in the element can be modified by keyboard controls like Ctrl-B for bold and so on. With some JavaScript and HTML to create basic GUI buttons, you can add a toolbar to the environment and extend the capabilities. With a bit more generalization to make the package customizable,  you end up with one of the many Rich Text editing packages out there, nicely summarized in this article.

In the past few years, all major browsers have adopted a more-or-less common set of supported editing features for the contentEditable mode: bold, italic, underlined, ordered and unordered lists, blockquotes, image and link insertion, and headings, along with general undo/redo, copy/paste, spellcheck functions and access to style-specific tinkering with font colors, sizes, and families, etc.. Note that other major structures like dl and table are not in this common list, nor are any semantic HTML phrase tags like var, code, kbd, or cite. The main differentiating aspect across editors is whether the JavaScript logic has been extended to provide more direct table controls or improved dialogs for the image and linking functions.

Still, each of these editors requires special work to use as DITA editors. The logical process is mostly handled by the server. The general approach is this:

  1. Provide a plugin interface to an editor of choice. I’ve tested CKEditor, Tiny MCE, FreeRTE, and Xinha. The interface allows for direct integration of commercial editors like Xopus and DITA Storm as well–in these cases, the DITA content is handled directly, bypassing the usual in/out transform and cleanup steps.
  2. Enable user preference for editors to be assigned. Free editing is available for anyone, and licensed users can get their assigned commercial editor after login.
  3. On an Edit request, access the DITA topic from storage as a stream, and transform the DITA stream into HTML with class attributes that hint at the desired restoration of the element later on.
  4. On a Save request, post-process the editor’s HTML stream using HTML Tidy or other HTML normalizing tools. This is because each browser has different behaviors for things like paragraph separation (<br> vs <p>), phrase markup (the bold requests are sometimes reverted to <strong> or <span style=”font-weight:bold”>), and special characters (particularly quotes).
  5. Next, transform that HTML back into DITA, using migration-oriented tactics to ensure accepted overall DITA structure.Note that it is perfectly possible to transform a complex DITA specialization into hinted HTML and then restore it back exactly. But in the unvalidated context of these free-form editors, you can’t guarantee that users will inherently know to follow the DITA rules when modifying original content. This tool depends on these assumptions:
    1. Most body content for simple DITA topics has nearly the same behaviors as for HTML, so most phrases and blocks will in fact be inherently valid.
    2. Use templates to establish best practice structures for authors to fill in. This includes pre-generated sections with titles and {start here} placeholders for direct input into the template “form.”
    3. In the save-as-DITA transforms, use pull-based templates to populate content into the expected valid locations. In this way, even if someone changes the valid location for a hinted element, the resulting saved version has that content in the correct location. This is exactly the same strategy as for building migration transforms for DITA–this process is effectively an HMTL to DITA migration every time you save.

    So as long as authors keep to the limitations of the authoring tool itself, this turns out to be a reliable and repeatable process.  Coaching in good minimalist techniques is very much part of the overall validation strategy!

  6. Finally, write the transformed DITA stream out to file storage using your back-end CMS interfaces.

In terms of overall user experience, interacting with this process is intended to be just like using any rich text, in-browser editor except that some choices (such as font styling) will be not be available, some labels use DITA equivalents, and we won’t expect users to create new documents from a totally blank page–a modicum of initial structure helps guide users in keeping to guidelines (here, the styling supports divs that are hinted as their DITA section equivalents in a task).

These toolbar choices and internal presentation are the target for how any editor based on contentEditable would be customized in the expeDITA environment. Since these components closely represent most of the DITA content “form factors,” it is possible to represent most specializations. The lack of Definition List in the contentEditable repertoire was disheartening to me until I realized that a template could be generated using an insertHTML control, although editing the internals (like editing table structures after insertion) remains as a JavaScript challenge down the road.

And that is how I’ve basically put lipstick on a pig, as it were. Whether you think DITA is the pig, or HTML, now that is another matter!

This entry was posted in collaboration, expeDITA. Bookmark the permalink.