convtags

convtags is a bidirectional converter beetween DokuWiki and AsciiDoc formatted text files.

What is convtags

convtags is a bidirectional converter:

DokuWiki => AsciiDoc => Dokuwiki

Written with portability in mind, it should work on any UNIX® like operating system.

Target use cases

• Convert a wiki powered by DokuWiki to a static website
• Ease the translation of a wiki powered by DokuWiki

Warning: the conversion from AsciiDoc to DokuWiki is only provided to convert back a document previously converted from DokuWiki to AsciiDoc. It can handle only a small subset of the AsciiDoc constructs, i.e. those that have a matching equivalent in DokuWiki.

Installation

Manual installation:

• Download the program convtags and the md5 hash file convtags.md5
• Check the integity of convtags using convtags.md5. This command: md5sum -c convtags should return:
• OK
• Ensure that convtags be executable and owned by root: chown root:root convtags; chmod 755 convtags
• move convtags in a suitable location, preferably /usr/bin: mv convtags /usr/bin

Dependencies

convtags has no hard dependency beyond a shell and some usual utilities found in all UNIX-like systems, mainly sed.

AsciiDoc is an obvious soft dependency.

Usage

After installation, type: convtags to get information on usage, settings, configuration and support.

Features and limitations

Most syntactic DokuWiki constructs can be converted to AsciiDoc.

Known limitations in the conversion from DokuWiki to AsciiDoc:

• No syntax checking is done of the input file.
• Appending a downloadable file (code snippet) to a Code block is not available (the link to the file is silently discarded by the converter).
• The links to a location in the same page are not converted.
• The vertical spanning (over several rows) of table cells is not provided.
• Text decorations and “text not to be parsed” marks are only converted if opening and closing marks are on the same line.
• Windows shares and Interwiki links are not converted.
• Embedding HTML and PHP is not available.
• RSS/Atom feed integration is not available.
• Text to image conversion is not available.
• External images (in DokuWiki parlance) are not displayed.

In addition to the basic DokuWiki syntax, the graphical rendering of admonitions (through the Note plugin) is converted.

Other plugins can be needed to properly display the documents in DokuWiki format, be it in the genuine or converted back ones. Examples are the Keyboard Syntax plugin, Info plugin, Tag plugin and HTML Comment plugin.

For syntax highlighting to show in AsciiDoc you need a proper utility, for instance source-highlight.

Author

Didier Spaier, Paris, France

This document was last updated on 19/04/2016