Creating DITA topics using reStructuredText
To a writer whose only tool is a flat text editor, formatted text is the next best thing to a real DITA editor.
Don Daymigration, editingIn fact, the process is one of the more reliable alternate authoring methods among those I've been writing about. Even the use of cell phone photos, while described facetiously for April Fools, has a place whenever the source format is so utterly obtuse that scanning the printout is the best way of filtering out the gorpy markup.
About reStructuredText
Popular examples of lightweight markup include theMediaWiki , Eclipse-basedMylyn , andCreolewikitext styles and their particular tools. DITA converters exist for some of these, notably for theMylyn project .
reStructuredText (also called rst or sometimes--conflicting with 'RESTful' API usage--reST) is popular in the Python programming community and has gained a recent boost in visibility by being recognized as a strategic markup strategy for materials in the Gutenberg Project. The part that appealed most to me about rst as a format is that the Python docutils toolkit includes a parser that generates an XML representation of the fully normalized document structure.Having an XML representation of a lightweight markup makes the subsequent migration as DITA vastly simpler and more reliable.
Process
Then I copied and pasted my "source" into a file, rstPost.txt, and used the rst2xml.py Python tool to generate an intermediate xml representation which I then converted into a DITA map and related subtopics using a set of XSLT transforms that I'm preparing for contribution to the DITA Open Toolkit. Finally, I used the expeDITA live map rendering feature to create the HTML view that I will paste into my WordPress blog in a few minutes.
Thoughts
The downside is that proper XML parsing is only possible using Python tools, which means that the process is not portable to servers based on popular Java or PHP stacks without using remote calls or web services. However, the reliability of the XML-based process makes the pain worth enduring for this case of at least one wikitext-like format that can support somewhat reliable migration into DITA wherever text-only content entry is your starting point.
rstPostoriginal text version
my_result_rstPostPDF from generated DITA source using DITA Open Toolkit