Home

Migrating reStructureText to DITA

This tool and process converts a reST document into a DITA map and constituent DITA topics. It does so through a two-step process that first converts the document into a well-formed XML equivalent of the original document after which the intermediate version is transformed via an XSLT process into a close DITA equivalent.

Known issues

reStructuredText permits extensions of the semantic markup via "directives" which bind with related Python processing. The local Python tools need to support any directives that are used in the document; this enables proper serialization as XML. [I don't know whether this use case is entirely indeterminate. Can someone verify?]

Likewise, the XSLT transform is based on known basic reST components and commonly used directives. If a body of information introduces a new and unsupported directive, one or more new transforms will need to be added. The markup produced by the transforms will likely be to a more semantic DITA element if there is an equivalent, or dumped to its closest DITA "archetype" with an outputclass attribute added that identifies the original reST semantic or dirctive name; this enables either CSS-based styling or "respecialization" steps in DITA to up-convert the designated structure to a better receiving specialization.