Both sides previous revisionPrevious revisionNext revision | Previous revision |
howtos:misc:dokuwiki_versus_asciidoc_markups [2015/04/15 21:54 (UTC)] – didierspaier | howtos:misc:dokuwiki_versus_asciidoc_markups [2015/10/05 12:43 (UTC)] (current) – didierspaier |
---|
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. |
| |
At the moment a "one way" converter Dokuwiki source page => AsciiDoc source page written by Didier Spaier is available [[http://slint.fr/misc/dokasc|here]] and can be used for instance to check the rendering of the pages of [[wiki:dokuwiki|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: | 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 | * create a new (empty) text file |
* click "edit this page" or "show pagesource" | * click "edit this page" or "show pagesource" in the page you want to convert and translate |
* select the whole text with Ctrl+Shift+A | * select the whole source text with Ctrl+Shift+A |
* copy and paste it in the text file | * copy and paste it in the text file |
* save the text file as ''dokuwiki_versus_asciidoc_markups'' then run:<code> | * save the text file as e.g. ''genuine.txt'' then run:<code> |
export FILE=dokuwiki_versus_asciidoc_markups | convtags da genuine.txt genuine.asc # convert to AsciiDoc |
sed -f dokasc1 $FILE|sed -f dokasc2 > $FILE.txt | convtags aw genuine.asc genuine.html # if you want to make a static web page (to run this command you need AsciiDoc) |
asciidoc -b xhtml11 -a icons -a iconsdir=/etc/asciidoc/images/icons -o $FILE.html $FILE.txt | firefox genuine.html # if you want to check the rendering of the static web page |
firefox $FILE.html& | po4a-gettextize -f asciidoc -m genuine.asc -M UTF8 -p genuine.po # to make a PO file containing only the text to translate |
unset FILE | 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> | </code> |
| You can then copy/paste the text of translated.txt as the source of the translated page. |
| |
Asciidoc and Firefox are included in a full Slackware installation.\\ | 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]]. | In addition, you will need to make and install a package [[http://slackbuilds.org/repository/14.1/development/source-highlight/|source-highlight]]. |
| |
Be aware of following limitations: | There are some limitations to the conversion from DokuWiki to AsciiDoc, see the [[http://slint.fr/misc/convtags/README|README]]. |
* 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 [[http://wiki.foosel.net/snippets/dokuwiki/keyboard|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 [[howtos:slackware_admin:building_the_linux_kernel_using_git_repository|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. | 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. | 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. | 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. |
| |
A few DokuWiki markups are not included in the table because they have no direct counterpart in AsciiDoc. | A few DokuWiki markups are not included in the table because they have no direct counterpart in AsciiDoc. |
|Superscript |%%<sup>text%%</sup>|%%^text^%%| 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. | | |Subscript |%%<sub>text</sub>%%|%%~text~%%| Does not span across paragraphs. | |
|Forced new line | %%\\⎕%% or \\↲|⎕+↲ |↲((↲ is U+21B2)) represents a line break and ⎕((⎕ is U+2395)) a space| | |Forced new line | %%\\⎕%% or \\↲|⎕+↲ |↲((↲ is U+21B2)) represents a <newline> and ⎕((⎕ is U+2395)) a space| |
|Ruler |%%----%% (at least 4 dashes) | %%↲'''%% (at least 3 single quotes) |draws an horizontal line | | |Ruler |%%----%% (at least 4 dashes) | %%↲'''%% (at least 3 single quotes) |draws an horizontal line | |
|Footnote | %%((text))%% |footnote:[<text>] |A: also with reference ID | | |Footnote | %%((text))%% |footnote:[<text>] |A: also with reference ID | |
|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.| | |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.| |
|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.| | |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.| |
|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)) | | |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) -> <- <-> => <= --- | | |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)| |
|External links |%%[[http://resource|text]]%% |%%https://resource[text]%% |http can be replaced by https, ftp, ftps| | |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| | |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%% |((http://docs.slackware.com/ can be replaced by another URL in the second script)) | | |Internal links |%%[[internal:link]]%% | %%internal:link%% | | |
|Internal links | %%[[internal:link|text]]%% |%%http:docs.slackware.com/internal:link[text]%% |((http://docs.slackware.com/ can be replaced by another URL in the second script)) | | |Internal links | %%[[internal:link|text]]%% |%%internal:link[text]%% | | |
|Email addresses |%%<local@domain>%% | %%local@domain%% or\\ %%mailto:local@domain[text]%%|A: other syntax mailto:local@domain[text]| | |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)| | |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))| |
|Unordered list |%%⎕⎕* item%% |* item| | | |Unordered list |%%⎕⎕* item%% |* item| | |
|Unordered list |%%⎕⎕⎕⎕* item%% |%%**%% item | | | |Unordered list |%%⎕⎕⎕⎕* item%% |%%**%% item | | |
|Admonitions |%%<note tip><text></tip>%%|[TIP] \\ ==== \\ 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| | |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 |%%⎕⎕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)...| |
|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 |%%<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| |
|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| | |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| |
|Highlighted source code|%%<code language> block </code>%%| [source,language] \\ %% ----%% \\ block \\ %%----%% |D: If language is "-" or ".", "shell is assumed. \\ A: converted to a Listing bloc\\ A: needs a syntax highlighting plugin.((The feature "downloadable attached file" is not converted as no such plugin is available for AsciiDoc. The link is discarded)) | | |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 ".", "shell is assumed. \\ A: converted to a Listing bloc\\ A: needs a syntax highlighting plugin.((The feature "downloadable attached file" is not converted as no such plugin is available for AsciiDoc. 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| | |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}} |
| |