[2024-feb-29] Sad news: Eric Layton aka Nocturnal Slacker aka vtel57 passed away on Feb 26th, shortly after hospitalization. He was one of our Wiki's most prominent admins. He will be missed.

Welcome to the Slackware Documentation Project

This is an old revision of the document!


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 can 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.

At the moment a “one way” converter Dokuwiki source page ⇒ AsciiDoc source page written by Didier Spaier is available here and can be used for instance to check the rendering of the pages of this wiki. This converter takes the form of a set of two UTF-8 encoded sed scripts to be executed sequentially. For instance to convert this page then display the result in Firefox:

  • create a new (empty) text file
  • click “edit this page” or “show pagesource”
  • select the whole text with Ctrl+Shift+A
  • copy and paste it in the text file
  • save the text file as dokuwiki_versus_asciidoc_markups then run:
    export FILE=dokuwiki_versus_asciidoc_markups
    sed -f dokasc1 $FILE|sed -f dokasc2 > $FILE.txt
    asciidoc -b xhtml11 -a icons -a iconsdir=/etc/asciidoc/images/icons -o $FILE.html $FILE.txt
    firefox $FILE.html&
    unset FILE

Asciidoc and Firefox are included in a full Slackware installation.
In addition, you will need to make and install a package source-highlight.

Be aware of following limitations:

  • The internal links are converted to point to this wiki.To can change that, find and replace http://docs.slackware.com by your target in the script file dokasc2
  • The internal images are not displayed.
  • The Keyboard syntax plugin for Dokuwki has no equivalent for AsciiDoc thus you won't get the same rendering after conversion to AsciiDoc.
  • Appending a downloadable file (code snippet) to a Code block is not possible in AsciiDoc thus the link to the file is silently discarded by the converter
  • Multi-level quoting is not available n AsciiDoc, but the converter tries to simulate this feature. You can see an example in converting this page.
  • The vertical spanning (over several rows) of a table cell is not provided
  • The horizontal spanning of a table cell is limited to 9 consecutive columns.
  • The text to image conversion is not available.

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.

The table below summarizes the rules set up for the conversion.

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.

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.

In the “Notes” column, D: stands for DokuWiki and A: for AsciiDoc.

Conversion Table and Cheat Sheet
Item DokuwikiAsciidocNotes
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 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
External links http://resource http://resource cf. RFC3986
http can be replaced by https, ftp, ftps
External links www.resource http://www.resource D: converted to http://www.resource
External links [[http://resource|text]] https://resource[text] http can be replaced by https, ftp, ftps
External links [[http://resource]] https://resource D: not documented but works
http can be replaced by https, ftp, ftps
Internal links [[internal:link]] http:docs.slackware.com/internal:link 7)
Internal links [[internal:link|text]] http:docs.slackware.com/internal:link[text] 8)
Email addresses <local@domain> local@domain or
mailto:local@domain[text]
A: other syntax mailto:local@domain[text]
Multi-level quoting > quoted text
>> quoted text
>>> quoted text
[verse]
----
quoted text
..quoted text
....quoted text
----
Feature not available in AsciiDoc but simulated by the converter. The quoted text is converted to an AsciiDoc Quote block with the style “verse”, thus the lines are reproduced as-is (no line break inserted)
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 space must 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 | cell merged with the two next right ||| 3+| (3 cells merged)D: the number of consecutive | on the right of the cell states the number of cells to be merged, that is converted to n+ in AsciDoc
D: same feature with consecutive ^ on the right of the cell
Cell vertical span::: (merged with next up) .m+| (m cells merged down)A: possibly preceded by n (n cells merged on the right)
This feature is not provided by the converter.
Admonitions <note><text></note>[NOTE]
====
block
====
A: or NOTE: paragraph
D: with the NOTE plugin9)
Admonitions <note important><text></important>[IMPORTANT]
====
block
====
A: Converted to an Admonition block
D: with the NOTE plugin
Admonitions <note tip><text></tip>[TIP]
====
block
====
A: Converted to an Admonition block
D: with the NOTE plugin
Admonitions <note warning><text></warning>[WARNING]
====
block
====
A: Converted to an Admonition block
D: with the NOTE plugin
Code block ⎕⎕line of text
⎕⎕line of text
----
block
----
A: converted to a Listing bloc
Code block <code> block </code> ----
block
----
A: converted to a Listing bloc
D: the opening and closing tags can occur anywhere on the line, but in case of continuation of a list item
Code block <file> block </file> ----
block
----
A: converted to a Listing bloc
D: the opening and closing tags can occur anywhere on the line, but in case of continuation of a list item
Highlighted source code<code language> block </code> [source,language]
----
block
----
D: If language is “-” or “.”, “txt' is assumed.
A: converted to a Listing bloc
A: needs a syntax highlighting plugin.10)
Highlighted source code<file language> block </file> [source,language]
----
block
----
D: If language is ”-“ or ”.“, “txt” is assumed.
A: converted to a Listing bloc
A: needs a syntax highlighting plugin.11)
Multiline list item see this article line of text
+
line of text
D: Code blocks can be embedded
A: Listing blocks can be embedded

Sources

* Originally written by Didier Spaier

1)
If used across paragraphs, merges them. I consider this as a bug in DokuWiki – Didier Spaier.
2)
↲ is U+21B2
3)
⎕ is U+2395
4)
“ is U+201C, ” is U+201D
5)
‘ is U+2018, ’ is U+2019
6)
Because that results in a merge of these paragraphs
7) , 8)
http://docs.slackware.com/ can be replaced by another URL in the second script
9)
The NOTE plugin is co-authored by Eric Hameleers & alii.
10) , 11)
The feature “downloadable attached file” is not converted as no such plugin is available for AsciiDoc. The link is discarded
 howtos:misc:dokuwiki_versus_asciidoc_markups ()