[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

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision
Previous revision
howtos:misc:dokuwiki_versus_asciidoc_markups [2015/04/15 21:54 (UTC)] didierspaierhowtos:misc:dokuwiki_versus_asciidoc_markups [2015/10/05 12:43 (UTC)] (current) didierspaier
Line 10: Line 10:
 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 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 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 AsciiDocsee the [[http://slint.fr/misc/convtags/README|README]].
-  * The internal links are converted to point to this wiki.To can change thatfind 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.
Line 40: Line 35:
 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.
Line 56: Line 51:
 |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)|
Line 72: Line 67:
 |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  | |
Line 95: Line 90:
 |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}}
  
 howtos:misc:dokuwiki_versus_asciidoc_markups ()