| Both sides previous revisionPrevious revisionNext revision | Previous revision |
| howtos:misc:dokuwiki_versus_asciidoc_markups [2015/04/13 10:16 (UTC)] – [Conversion Table and Cheat Sheet] didierspaier | howtos:misc:dokuwiki_versus_asciidoc_markups [2015/10/05 12:43 (UTC)] (current) – didierspaier |
|---|
| At time of writing, [[http://docs.slackware.com/|SlackDocs]] uses a DokuWiki engine to convert the wiki pages (plain text including markup) to xhtml text. | At time of writing, [[http://docs.slackware.com/|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. | 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": | This conversion should be "bi-directional": |
| |
| Dokuwiki source page => AsciiDoc source page => PO file => Translated PO file => AsciiDoc translated page => Dokuwiki translated page. | 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. | The ''convtags'' converter written by Didier Spaier is available [[http://slint.fr/misc/convtags|here]]. This converter takes the form of a set of UTF-8 encoded sed scripts. For instance to convert a page from this wiki to AsciiDoc, display the result in Firefox, translate it then convert it back to DokuWiki: |
| | * create a new (empty) text file |
| | * click "edit this page" or "show pagesource" in the page you want to convert and translate |
| | * select the whole source text with Ctrl+Shift+A |
| | * copy and paste it in the text file |
| | * save the text file as e.g. ''genuine.txt'' then run:<code> |
| | convtags da genuine.txt genuine.asc # convert to AsciiDoc |
| | convtags aw genuine.asc genuine.html # if you want to make a static web page (to run this command you need AsciiDoc) |
| | firefox genuine.html # if you want to check the rendering of the static web page |
| | po4a-gettextize -f asciidoc -m genuine.asc -M UTF8 -p genuine.po # to make a PO file containing only the text to translate |
| | lokalize genuine.po # to translate. You could also use emacs or vim in PO mode, or poedit available @ slackbuilds.org |
| | po4a-translate -f asciidoc -m genuine.asc -p genuine.po -l translated.asc # to make an asciidoc file from your translation |
| | convtags ad translated.asc translated.txt # convert back your translation to DokuWiki |
| | </code> |
| | You can then copy/paste the text of translated.txt as the source of the translated page. |
| |
| This needs to match each DokuWiki syntax item with a corresponding AsciiDoc syntax item. | Asciidoc and Firefox are included in a full Slackware installation.\\ |
| | In addition, you will need to make and install a package [[http://slackbuilds.org/repository/14.1/development/source-highlight/|source-highlight]]. |
| |
| A basis for the conversion is proposed in the table below. | There are some limitations to the conversion from DokuWiki to AsciiDoc, see the [[http://slint.fr/misc/convtags/README|README]]. |
| |
| The converter is not yet available, and its full feasibility not even demonstrated. However this table is already provided: | 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. |
| * 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. | The table below summarizes the rules set up for the conversion. |
| |
| 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. | 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 can be automatically converted to DokuWiki. |
| |
| <rant>Setting this conversion table was not straightforward as AsciiDoc lacks a "real" formal definition of its syntax in the [[http://www.methods.co.nz/asciidoc/userguide.html|AsciiDoc User Guide]] and even worse the [[http://docs.slackware.com/wiki:syntax|DokuWiki formatting syntax]] just provides examples.</rant> | 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 [[http://www.methods.co.nz/asciidoc/userguide.html|AsciiDoc User Guide]] and even worse the [[http://docs.slackware.com/wiki:syntax|DokuWiki formatting syntax]] just provides examples. |
| |
| ====Conversion Table and Cheat Sheet==== | |
| In the "Notes" column, D: stands for DokuWiki and A: for AsciiDoc. | In the "Notes" column, D: stands for DokuWiki and A: for AsciiDoc. |
| ^Item ^Dokuwiki ^Asciidoc ^Notes ^ | ^ Conversion Table and Cheat Sheet |||| |
| | emphasized | %%//%% |%%__%% | D: rendered as //italic//. Does not span across paragraphs.((If used across paragraphs, merges them. I consider this as a bug in DokuWiki -- Didier Spaier.)) \\ Several text decorations (emphasized, strong, monospaced, underlined, strike through) can be nested in both syntax. Quoting cannot be overlapped. | | |**Item** |**Dokuwiki**|**Asciidoc**|**Notes**| |
| | strong | %%**%% | %%**%% | D: rendered as **bold**. Does not span across paragraphs.| | |Emphasized | %%//%% |%%__%% | D: rendered as //italic//. Does not span across paragraphs.((If used across paragraphs, merges them. I consider this as a bug in DokuWiki -- Didier Spaier.)) \\ Several text decorations (emphasized, strong, monospaced, underlined, strike through) can be nested in both syntax. Quoting cannot be overlapped. | |
| | monospaced | %%''%% | ++|A: other syntax ` but only on word boundaries, implies no further expansion. \\ Does not span across paragraphs.| | |Strong | %%**%% | %%**%% | D: rendered as **bold**. 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. | | |Monospaced | %%''%% | ++|A: other syntax ` but only on word boundaries, implies no further expansion. \\ 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.| | |Underlined | %%__%% |%%[underline]#text#%% | A: # can be replaced by markup for strong, monospaced and/or underlined. Does not span across paragraphs. | |
| |superscript |%%<sup>text%%</sup>|%%^text^%%| 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.| |
| |subscript |%%<sub>text</sub>%%|%%~text~%%| Does not span across paragraphs. | | |Superscript |%%<sup>text%%</sup>|%%^text^%%| Does not span across paragraphs. | |
| |forced new line | %%\\▯%% or \\↲|▯+↲ |↲((↲ is U+21B2)) represents a line break and ▯((▯ is U+200B)) a white space| | |Subscript |%%<sub>text</sub>%%|%%~text~%%| Does not span across paragraphs. | |
| |ruler |%%----%% (at least 4 dashes) | %%↲'''%% (at least 3 single quotes) |draws an horizontal line | | |Forced new line | %%\\⎕%% or \\↲|⎕+↲ |↲((↲ is U+21B2)) represents a <newline> and ⎕((⎕ is U+2395)) a space| |
| |footnote | %%((text))%% |footnote:[<text>] |A: also with reference ID | | |Ruler |%%----%% (at least 4 dashes) | %%↲'''%% (at least 3 single quotes) |draws an horizontal line | |
| |double quotation marks| %%"text"%% | ``text''|Rendering: “text”((“ is U+201C, ” is U+201D)). \\ D: replacement depends on 'typography' setting in configuration file.\\ A: only on word boundaries, no span across paragraphs.| | |Footnote | %%((text))%% |footnote:[<text>] |A: also with reference ID | |
| |single quotation marks | %%'text'%% | `text' |Rendering: ‘text’((‘ is U+2018, ’ is U+2019)). \\ D: replacement depends on 'typography' setting in configuration file.\\ A: only on word boundaries, no span across paragraphs.| | |Double quotation marks| %%"text"%% | %%``text''%%|Rendering: “text”((“ is U+201C, ” is U+201D)). \\ 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 paragraphs((Because that results in a merge of these paragraphs)) | | |Single quotation marks | %%'text'%% | %%`text'%% |Rendering: ‘text’((‘ is U+2018, ’ is U+2019)). \\ D: replacement depends on 'typography' setting in configuration file.\\ A: only on word boundaries, no span across paragraphs.| |
| |replacements |%%(c) (tm) (r) -> <- => <= ---%% | %%(C) (TM) (R) -> <- => <= --%% | Rendering : (c) (tm) (r) -> <- <-> => <= --- | | |No formatting (passthrough) | <nowiki>%%text with markup%%</nowiki> 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 paragraphs((Because that results in a merge of these paragraphs)) | |
| | |Replacements |%%(c) (tm) (r) -> <- => <= ---%% | %%(C) (TM) (R) -> <- => <= --%% | Rendering : (c) (tm) (r) -> <- <-> => <= --- | |
| |Heading | ======text====== |= text |Heading level 1 (title)| | |Heading | ======text====== |= text |Heading level 1 (title)| |
| |Heading | =====text===== |== title |Heading level 2 | | |Heading | =====text===== |== title |Heading level 2 | |
| |Heading | ===text=== |==== text |Heading level 4 | | |Heading | ===text=== |==== text |Heading level 4 | |
| |Heading | ==text== |===== text |Heading level 5 | | |Heading | ==text== |===== text |Heading level 5 | |
| |links |%%http://resource%% |%%http://resource%% |cf. RFC3986 | | |External links |%%http://resource%% |%%http://resource%% |cf. RFC3986 \\ http can be replaced by https, ftp, ftps | |
| |links |%%www.resource%% |%%http://www.resource%% |D: converted to %%http://www.resource%%| | |External links |%%www.resource%% |%%http://www.resource%% |D: converted to %%http://www.resource%%| |
| |links |%%https://resource%% |%%https://resource%% | | | |External links |%%[[http://resource|text]]%% |%%https://resource[text]%% |http can be replaced by https, ftp, ftps| |
| |links |%%[[http://resource|text]]%% |%%https://resource[text]%% | | | |External links |%%[[http://resource]]%% |%%https://resource%% |D: not documented but works \\ http can be replaced by https, ftp, ftps| |
| |links |%%[[https://resource|text]]%% |%%https://resource[text]%% | | | |Internal links |%%[[internal:link]]%% | %%internal:link%% | | |
| |links |%%ftp://resource%% |%%ftp://resource%% | | | |Internal links | %%[[internal:link|text]]%% |%%internal:link[text]%% | | |
| |links |%%ftps://resource%% |%%ftps://resource%% | | | |Email addresses |%%<local@domain>%% | %%local@domain%% or\\ %%mailto:local@domain[text]%%|A: other syntax mailto:local@domain[text]| |
| |links |%%[[ftp://resource|text]]%% |%%ftp://resource[text]%% | | | |Multi-level quoting| %%> quoted text%% \\ %%>> quoted text%% \\ %%>>> quoted text%% | │quoted text \\ ││quoted text \\ %%│││quoted text%% | Feature not available in AsciiDoc but ''simulated by the converter''.((The light vertical │ is U+2502))| |
| |links |%%[[ftps://resource|text]]%% |%%ftps://resourc[text]%% | | | |Unordered list |%%⎕⎕* item%% |* item| | |
| |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 | | |
| |unordered list |%%▯▯▯▯▯▯* item%% |%%***%% item | | | |Unordered list |%%⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕* item%% |%%*****%% item | | |
| |unordered list |%%▯▯▯▯▯▯▯▯* item%% |%%****%% item | | | |Ordered 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 | | |
| |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)| |
| |ordered list |%%▯▯▯▯▯▯▯▯▯▯- item%% |%%....%% item | | | |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| |
| |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 horizontal alignment|%%|%%left %%| %%center %%|%% right%%|%% |%%<|left ^|center >|right%% |A: %%<,^ or >%% possibly followed by "h" or another table style| |
| |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 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 horizontal alignment|%%|%%left %%|%% center %%|%% right%%|%%|%%<|left ^| center >|right%%|A: %%<,^ or >%% possibly followed by "h" or another table style| | |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''.| |
| |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)| | |Admonitions |%%<note><text></note>%%|[NOTE] \\ ==== \\ block \\ ==== |A: or NOTE: paragraph \\ D: with the NOTE plugin((The NOTE plugin is co-authored by Eric Hameleers & alii.))| |
| |cell vertical span|::: (merged with next up)| .m+%%|%% (m cells merged down)|A: possibly preceded by n (n cells merged on the right)| | |Admonitions |%%<note important><text></important>%%|[IMPORTANT] \\ ==== \\ block \\ ==== |A: Converted to an Admonition block \\ D: with the NOTE plugin| |
| |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 lines((This cuts the first and/or last line(s).)), and the opening tag can include the name of a downloadable file (this last feature can't be easily converted). \\ A: Listing block| | |Admonitions |%%<note tip><text></tip>%%|[TIP] \\ ==== \\ block \\ ==== |A: Converted to an Admonition block \\ D: with the NOTE plugin| |
| |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 warning><text></warning>%%|[WARNING] \\ ==== \\ block \\ ==== |A: Converted to an Admonition block \\ D: with the NOTE plugin| |
| |Admonitions |%%<note><text></note>%%|[NOTE]↲ paragraph |A: or NOTE: paragraph \\ D: with the NOTE plugin((The NOTE plugin is co-authored by Eric Hameleers & alii.))| | |Code block |%%⎕⎕line of text %% \\ %%⎕⎕line of text %% |%%----%% \\ block \\ %%----%% |A: converted to a Listing block \\ D: Actually, the Code block will be formatted as such only if it includes a line containing at least one character belonging to the POSIX character class ''graph''. And the first line beginning with two spaces won't begin a Code block if the previous one included a closing %%</code>%% or %%</file>%% ot %%</note>%% only followed by one or several space(s)...| |
| |Admonitions |%%<important><text></important>%%|[IMPORTANT]↲ paragraph |A: or IMPORTANT: paragraph \\ D: with the NOTE plugin| | |Code block |%%<code> block </code>%% |%%----%% \\ block \\ %%----%% |A: converted to a Listing block \\ D: the opening and closing tags can occur anywhere on the line, but in case of continuation of a list item| |
| |Admonitions |%%<tip><text></tip>%%|[TIP]↲ paragraph |A: or TIP: paragraph \\ D: with the NOTE plugin| | |Code block |%%<file> block </file>%% |%%----%% \\ block \\ %%----%% |A: converted to a Listing block\\ D: the opening and closing tags can occur anywhere on the line, but in case of continuation of a list item| |
| |Admonitions |%%<warning><text></warning>%%|[WARNING]↲ paragraph |A: or WARNING: paragraph \\ D: with the NOTE plugin| | |Highlighted source code|%%<code language> block </code>%%| [source,language] \\ %% ----%% \\ block \\ %%----%% |D: If language is "-" or ".", "txt' is assumed. \\ A: converted to a Listing block\\ A: needs a syntax highlighting plugin.((The feature "downloadable attached file" is not converted. The link is discarded)) | |
| | |Highlighted source code|%%<file language> block </file>%%| [source,language] \\ %%----%% \\ block \\ %%----%% |D: If language is "-" or ".", "txt" is assumed. \\ A: converted to a Listing block\\ A: needs a syntax highlighting plugin.((The feature "downloadable attached file" is not converted. The link is discarded)) | |
| | |Multiline list item| see [[https://www.dokuwiki.org/faq:lists|this article]] | line of text \\ + \\ line of text |D: Code blocks can be embedded \\ A: Listing blocks can be embedded| |
| | |Images| %%{{ <source>[?]<linking>&<width>x<height>|<title>] }}%%|image::<target>[<attributes>]\\ where <attributes> is a comma separated list|See the comments in the program ''convtags'' for the details | |
| |
| ====== Sources ====== | ====== Sources ====== |
| * Originally written by [[wiki:user:didierspaier | Didier Spaier]] | * Originally written by [[wiki:user:didierspaier | Didier Spaier]] |
| {{tag>howtos}} | {{tag>howtos}} |
| | |
