Both sides previous revisionPrevious revisionNext revision | Previous revisionLast revisionBoth sides next revision |
howtos:misc:dokuwiki_versus_asciidoc_markups [2015/06/27 07:39 (UTC)] – Way of converting multi-level quoting simplified didierspaier | howtos:misc:dokuwiki_versus_asciidoc_markups [2015/10/05 02:42 (UTC)] – [Introduction] 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 at time of writing: | 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 change that, find and replace http://docs.slackware.com by your target in the script file dokasc2.((Removing this limitation is in the TODO list)) | |
* The internal images are not displayed.((Removing this limitation is in the TODO list)) | |
* 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 yet available thus the link to the file is silently discarded by the converter.((Removing this limitation is in the TODO list)) | |
* Multi-level quoting is not available in AsciiDoc, but the converter simulated 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. | |
* Text decorations and "text not to be parsed" marks are only properly converted if opening and closing marks are on the same line.((Removing this limitation is in the TODO list)) | |
| |
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. |
|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%% | │quoted text \\ ││quoted text \\ %%│││quoted text%% | Feature not available in AsciiDoc but ''simulated by the converter''.((The light vertical │ is U+2502))| | |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))| |
|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 block | | |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 block \\ 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 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 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 ".", "txt' is assumed. \\ A: converted to a Listing block\\ A: needs a syntax highlighting plugin.((The feature "downloadable attached file" is not converted yet. 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 ".", "txt" is assumed. \\ A: converted to a Listing block\\ A: needs a syntax highlighting plugin.((The feature "downloadable attached file" is not converted yet. 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 ====== |