User Tools

Site Tools


en:dokuwiki_versus_asciidoc_markups

Differences

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

Link to this comparison view

en:dokuwiki_versus_asciidoc_markups [2016/12/13 10:30]
didier [The Cross Syntax Cheat Sheet: DokuWiki versus AsciiDoc Markups]
en:dokuwiki_versus_asciidoc_markups [2019/11/18 12:54]
Line 1: Line 1:
-=====The Cross Syntax Cheat Sheet: DokuWiki versus AsciiDoc Markups===== 
-~~NOTOC~ 
- 
-====Introduction==== 
-At time of writing, this wiki 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. 
- 
-The ''​convtags''​ converter written by Didier Spaier is available [[https://​github.com/​DidierSpaier/​convtags/​releases|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.  
- 
-Asciidoc and Firefox are included in a full Slackware installation.\\ 
-In addition, you will need to make and install a package source-highlight. To do that in Slint just type: 
-  spi -i source-highlight 
- 
-There are some limitations to the conversion from DokuWiki to AsciiDoc, see the [[https://​github.com/​DidierSpaier/​convtags/​blob/​master/​README.md|README]]. 
- 
-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 can 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 [[http://​www.methods.co.nz/​asciidoc/​userguide.html|AsciiDoc User Guide]] and even worse the [[wiki:​syntax|DokuWiki formatting Syntax]] just provides examples. 
- 
-In the "​Notes"​ column, D: stands for DokuWiki and A: for AsciiDoc. 
-^  Conversion Table and Cheat Sheet  |||| 
-|**Item** |**Dokuwiki**|**Asciidoc**|**Notes**| 
-|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. | 
-|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 \\↲|⎕+↲ |↲((↲ 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 | 
-|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.| 
-|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) ​  | <​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===== ​                   |== 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]]%% | %%internal:​link%% | | 
-|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]| 
-|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  | | 
-|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 plugin((The NOTE plugin is co-authored by Eric Hameleers & alii.))| 
-|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 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       ​|%%<​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. 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 ====== 
-  * Originally written by Didier Spaier 
  
en/dokuwiki_versus_asciidoc_markups.txt · Last modified: 2019/11/18 12:54 (external edit)