This is an old revision of the document!
Table of Contents
The Cross Syntax Cheat Sheet: DokuWiki versus AsciiDoc Markups
Introduction
At time of writing, SlackDocs uses a DokuWiki engine to convert the wiki pages (plain text including markup) to xhtml text.
Converting the DokuWiki markup to AsciiDoc markup would ease the work of translators of DokuWiki pages, as the application po4a, that allows to produce PO files ready for translation, can handle the AsciiDoc markup but not the DokuWiki markup.
This conversion should be “bi-directional”:
Dokuwiki source page ⇒ AsciiDoc source page ⇒ PO file ⇒ Translated PO file ⇒ AsciiDoc translated page ⇒ Dokuwiki translated page.
In addition to easing the translation, the converter could be used e.g. to convert a static website build from AsciiDoc source pages to a Wiki powered by DokuWiki or reverse.
This needs to match each DokuWiki syntax item with a corresponding AsciiDoc syntax item.
A basis for the conversion is proposed in the table below.
The converter is not yet available, and its full feasibility not even demonstrated. However this table is already provided:
- for review by people knowing both syntax
- as a request for comments
- as (yet another) DokuWiki Cheat Sheet
This table can not be used as an AsciiDoc Cheat Sheet because it includes only the markup needed for bi-directional conversion: the Asciidoc syntax is far richer. This also implies that only this subset of the Asciidoc markup could be automatically converted to DokuWiki.
A few DokuWiki markups are not included in the table because they have no direct counterpart in AsciiDoc, e.g.: internal links, text to image conversions, links to images or emails-like multilevel quoting.
<rant>Setting this conversion table was not straightforward as AsciiDoc lacks a “real” formal definition of its syntax in the AsciiDoc User Guide and even worse the DokuWiki formatting syntax just provides examples.</rant>
Conversion Table and Cheat Sheet
In the “Notes” column, D: stands for DokuWiki and A: for AsciiDoc.
| Item | Dokuwiki | Asciidoc | Notes |
|---|---|---|---|
| emphasized | // | __ | D: rendered as italic. Does not span across paragraphs.1) Several text decorations (emphasized, strong, monospaced, underlined, strike through) can be nested in both syntax. Quoting cannot be overlapped. |
| strong | ** | ** | D: rendered as bold. Does not span across paragraphs. |
| monospaced | '' | ++ | A: other syntax ` but only on word boundaries, implies no further expansion. Does not span across paragraphs. |
| underlined | __ | [underline]#text# | A: # can be replaced by markup for strong, monospaced and/or underlined. Does not span across paragraphs. |
| strike through | <del>text</del> | [line-through]#text# | A: # can be replaced by a markup for strong, monospaced and/or underlined. Does not span across paragraphs. |
| superscript | <sup>text</sup> | ^text^ | Does not span across paragraphs. |
| subscript | <sub>text</sub> | ~text~ | Does not span across paragraphs. |
| forced new line | \\▯ or \\↲ | ▯+↲ | ↲2) represents a line break and ▯3) a white space |
| ruler | ---- (at least 4 dashes) | ↲''' (at least 3 single quotes) | draws an horizontal line |
| footnote | ((text)) | footnote:[<text>] | A: also with reference ID |
| double quotation marks | "text" | ``text'' | Rendering: “text”4). D: replacement depends on 'typography' setting in configuration file. A: only on word boundaries, no span across paragraphs. |
| single quotation marks | 'text' | `text' | Rendering: ‘text’5). D: replacement depends on 'typography' setting in configuration file. A: only on word boundaries, no span across paragraphs. |
| no formatting (passthrough) | %%text with markup%% or: <nowiki>text with markup</nowiki> | +++text with markup+++ | A: provides also a syntax for passthrough blocks of text, but useless for the conversion, as practically in Dokuwiki the markup should not span over paragraphs6) |
| replacements | (c) (tm) (r) -> <- => <= --- | (C) (TM) (R) -> <- => <= -- | Rendering : © ™ ® → ← ↔ ⇒ ⇐ — |
| Heading | ======text====== | = text | Heading level 1 (title) |
| Heading | =====text===== | == title | Heading level 2 |
| Heading | ====text==== | === text | Heading level 3 |
| Heading | ===text=== | ==== text | Heading level 4 |
| Heading | ==text== | ===== text | Heading level 5 |
| links | http://resource | http://resource | cf. RFC3986 |
| links | www.resource | http://www.resource | D: converted to http://www.resource |
| links | https://resource | https://resource | |
| links | [[http://resource|text]] | https://resource[text] | |
| links | [[https://resource|text]] | https://resource[text] | |
| links | ftp://resource | ftp://resource | |
| links | ftps://resource | ftps://resource | |
| links | [[ftp://resource|text]] | ftp://resource[text] | |
| links | [[ftps://resource|text]] | ftps://resourc[text] | |
| email addresses | <local@domain> | local@domain or mailto:local@domain[text] | A: other syntax mailto:local@domain[text] |
| unordered list | ▯▯* item | * item | |
| unordered list | ▯▯▯▯* item | ** item | |
| unordered list | ▯▯▯▯▯▯* item | *** item | |
| unordered list | ▯▯▯▯▯▯▯▯* item | **** item | |
| unordered list | ▯▯▯▯▯▯▯▯▯▯* item | ***** item | |
| ordered list | ▯▯- item | . item | |
| ordered list | ▯▯▯▯- item | .. item | |
| ordered list | ▯▯▯▯▯▯- item | ... item | |
| ordered list | ▯▯▯▯▯▯▯▯- item | .... item | |
| ordered list | ▯▯▯▯▯▯▯▯▯▯- item | .... item | |
| tables | | text | text | | [table and column spec] |=== | text | text |=== | A: [table and column spec] is optional |=== delimit the table (at least three equal signs) |
| cell header | ^header | h|header | A: h can be preceded by other formatting instructions. if not before the leftmost column, a blank space should precede the first formatting instruction |
| cell horizontal alignment | |left | center | right| | <|left ^| center >|right | A: <,^ or > possibly followed by “h” or another table style |
| cell horizontal span | | (merged with next right cell))|| | n+| (n cells merged on the right) | A: n+ can be followed by other formatting instructions and P preceded by .m (m columns merged down) |
| cell vertical span | ::: (merged with next up) | .m+| (m cells merged down) | A: possibly preceded by n (n cells merged on the right) |
| Code blocks | ▯▯line of text ▯▯line of text <code> block of text </code> <file> block of text </file> | ---- block of text ---- | The block of text can span over paragraphs. D: the 3 forms give the same output. If one of the two last forms is used, the block can begin and/or end anywhere in the first and/or last lines7), and the opening tag can include the name of a downloadable file (this last feature can't be easily converted). A: Listing block |
| Source code with highlighted syntax | <code python> block of text </code> <file python> block of text </file> | [source,python] ---- block of text ---- | A: Listing Block A: another syntax exists to highlight a single paragraph: [source,python] paragraph |
| Admonitions | <note><text></note> | [NOTE]↲ paragraph | A: or NOTE: paragraph D: with the NOTE plugin8) |
| Admonitions | <important><text></important> | [IMPORTANT]↲ paragraph | A: or IMPORTANT: paragraph D: with the NOTE plugin |
| Admonitions | <tip><text></tip> | [TIP]↲ paragraph | A: or TIP: paragraph D: with the NOTE plugin |
| Admonitions | <warning><text></warning> | [WARNING]↲ paragraph | A: or WARNING: paragraph D: with the NOTE plugin |
Sources
* Originally written by Didier Spaier
