====== Creole Plugin ======

---- plugin ----
description: Creole is an initiative to bring a common basic set of wiki markup to different wiki engines. (previous author: Esther Brunner)
author     : Gina Häußge, Michael Klier
email      : dokuwiki@chimeric.de
type       : syntax
lastupdate : 2008-02-12
compatible : 2006-11-06
depends    : 
conflicts  : 
similar    : 
tags       : creole, wiki syntax
----

^  Download | [[http://www.chimeric.de/_src/plugin-creole.tgz|plugin-creole.tgz]] |

===== Description =====

The [[http://www.wikicreole.org/wiki/Creole0.3|Creole 0.3 Specs]] (2006-12-19) are very close to the [[:syntax]] used by DokuWiki. Only those elements differ:

  * [[#Listblock]]
  * [[#Headings]]
  * [[#Linebreaks]]
  * [[#Preformatted]]
  * [[#Tables]] (optional ending pipe not yet supported -- I'm working on a new version)

This [[plugins|Plugin]] will interpret Creole elements that are not understood by DokuWiki. If the markup collides (as with the header level order), by default DokuWiki's standard markup takes precedence.((You can change the markup precedence to Creole with the [[:config]] manager, if you want full Creole support.)) With the exception of the changed behaviour for linebreaks, all your existing wiki pages will look the same.

If you use this plugin to support the Creole syntax, you might want to list your wiki at http://www.wikicreole.org/wiki/WikisSupportingCreole

===== Components =====

==== Listblock ====

Creole style ordered and unordered lists use a slightly different markup:

Creole (and DokuWiki):

<code>
* Item 1          (  * Item 1     )
** Item 1.1       (    * Item 1.1 )
* Item 2          (  * Item 2     )
</code>

Output:

  * Item 1
    * Item 1.1
  * Item 2

Creole (and DokuWiki):

<code>
# Item 1          (  - Item 1     )
## Item 1.1       (    - Item 1.1 )
# Item 2          (  - Item 2     )
</code>

Output:

  - Item 1
    - Item 1.1
  - Item 2


==== Headings ====

In Creole, the header ordering is just the other way round. If you have set the markup precedence option to DokuWiki (default), this plugin will assume headers are DokuWiki style if there are equal signs after the title. In Creole, closing (right-side) equal signs are optional. So if omit them, headers are interpreted as Creole.

Creole (and DokuWiki):

<code>
= Level 1        (====== Level 1 ======)
== Level 2       (===== Level 2 =====  )
=== Level 3      (==== Level 3 ====    )
==== Level 4     (=== Level 4 ===      )
===== Level 5    (== Level 5 ==        )
</code>

Output:

====== Level 1 ======
===== Level 2 =====
==== Level 3 ====
=== Level 4 ===
== Level 5 ==

==== Linebreaks ====

DokuWiki does not care about (single) line breaks. Creole, however, does treat line breaks in the source as line breaks in the output.

This component is mainly the same as Chris Smith's [[linebreak]] plugin. Thanks!

==== Preformatted ====

Creole:

<code>
{{{
//This// does **not** get [[formatted]]
}}}

Some examples of markup are: {{{** <i>this</i> ** }}}
</code>

Output:

  //This// does **not** get [[formatted]]

Some examples of markup are: ''%%** <i>this</i> ** %%''

==== Tables ====

Creole (and DokuWiki):

<code>
|Heading Col 1  |Heading Col 2 |   (^Heading Col 1  ^Heading Col 2 ^)
|Cell 1.1       |Cell 1.2      |   (|Cell 1.1       |Cell 1.2      |)
|Cell 2.1       |Cell 2.2      |   (|Cell 2.1       |Cell 2.2      |)
</code>

Output:

|Heading Col 1  |Heading Col 2 |
|Cell 1.1       |Cell 1.2      |
|Cell 2.1       |Cell 2.2      |

The difference to DokuWiki is that in Creole there's no special markup for header cells and no cell alignment. In turn, in Creole the ending pipe is optional.

===== Bugs =====
Please report bugs at the [[http://bugs.chimeric.de/index.php?project=8&switch=1&do=index|Bug tracker]].

===== Further Resources =====
  * [[http://darcs.chimeric.de/darcsweb.cgi?r=creole|Darcs Repository]]
  * [[http://bugs.chimeric.de/index.php?project=8&switch=1&do=index|Bug tracker]]
  * [[http://dev.chimeric.de/codereference/nav.html?plugins/creole/index.html|Source code]]



===== Todo =====
  * make toolbar work
  * update to Creole 1.0 specs





===== Discussion =====

Very nice! The image notation in the Creole Markup however conflicts with the syntax for plugins in dokuwiki. If Dokuwiki is planning to change at some point in time to Creole, it might be wise to switch to the proposed 'internal markup' style <<x>> for plugins.  For anyone to use this plugin, a modification of the toolbar would be needed; do I have to change the toolbar manually or could the plugin be able to override the inserted syntax? Also, is there any converter for existing wiki pages? 
 --- //[[Niklas]] 2006-12-19 09:16//

> I don't know if a plugin can override the toolbar code, but I hard-coded reversed headings some time ago using [[tips:reverseheadertags|these tips]]. With the Creole plugin installed, all you have to change is the headings section in toolbar.php (to get an idea: [[tips:reverseheadertags#inc_toolbar.php|look here]]. 
>As for the converter: I once thought about writing a little script, but then decided to make it by hand. But if you want to do so. It should be relatively easy: Just go trough the text of each of your pages (with old syntax) and replace each occurence of a headline with a unique symbol (like '======' -> 'XXXH1XXX', '=====' -> 'XXXH2XXX' ...). Then you go through the text again and replace your unique identifiers with the new syntax ('XXXH1XXX' -> '==', 'XXXH2XXX -> '===' ...). By going through the text twice, you avoid conflicts of old and new headline syntax.
> As for the other syntax changes: You don't have to change anything, as DW understands both old and new syntax for lists and no-wiki. --- //[[unixprog@gmail.com|konstantin baierer]] 2006-12-19 15:47//

>> Good point about the replacement. The reverse header tags page is only semi-useful to me: I really don't want to patch a single line of code, I only want to use plugins that can be installed via the plugin manager. The reason is that even though I am setting up the wiki and hacking around is no problem at akk, I won't be the one maintaining it in the future, so I should and will not assume that the future maintainer will be able to cope with actual source code. //[[Niklas]] 2006-12-19 23:32//

>>> Hi Niklas and Konstantin. With an additional event hook in inc/toolbar.php, it would finally be possible for plugins to modify the toolbar. Let's ask Andi and the other developers whether they are open for this idea. --- //[[wikidesign@gmail.com|Esther Brunner]] 2006-12-20 00:53//

>>>> As I had to make a fresh installation today, I wrote that script mentioned above in perl. It reverses all header tags from dokuwiki to creole notation for a file given as argument. 

<code perl>
#!/usr/bin/perl -w
# revheaders
# Convert dokuwiki headers to creole headers

foreach (@ARGV) {
    $original = $metaformat = '';
    $filename = $_;
    open WIKIPAGE, ("<$filename");
    while (<WIKIPAGE>){
        $original .= $_;
        $_ =~ s/^======(.*)+?(======)/Xh1hX$1/g;
        $_ =~ s/^=====(.*)+?(=====)/Xh2hX$1/g;
        $_ =~ s/^====(.*)+?(====)/Xh3hX$1/g;
        $_ =~ s/^===(.*)+?(===)/Xh4hX$1/g;
        $_ =~ s/^==(.*)+?(==)/Xh5hX$1/g;
        $metaformat.= $_;
    }
    $metaformat =~ s/^Xh1hX(.*)/==$1==/gm;
    $metaformat =~ s/^Xh2hX(.*)/===$1===/gm;
    $metaformat =~ s/^Xh3hX(.*)/====$1====/gm;
    $metaformat =~ s/^Xh4hX(.*)/=====$1=====/gm;
    $metaformat =~ s/^Xh5hX(.*)/======$1======/gm;
    open BACKUP, ">$filename.BAK";
    print BACKUP $original;
    open WIKIPAGE, (">$filename");
    print WIKIPAGE $metaformat;
}
</code>
>>>> The original file is overwritten, a backup is made to oldname.BAK. 
>>>> If you want to convert a single file, just type ''perl revheaders FILENAME''. To rename a whole directory, go to the base of it and type ''find . -regex '.*txt' | xargs perl revheaders''. That will convert all .txt-files in this and all subsequent folders. If you want to undo your changes, just run the script again with the same file(s). It's especially useful to mass rename the builtin wiki pages in ''/inc/lang/''.  --- //[[unixprog@gmail.com|konstantin baierer]] 2007-03-31 22:27//

Thank you, for this very nice plugin.  --- //[[dokuwiki@companje.nl|Rick Companje]] 2007-12-20 17:52//

Wanted to point out that going to Creole 1.0 is not a big leap.  I wrote a couple additions for the [[http://www.wikicreole.org/wiki/CreoleAdditions|Creole 1.0 Additions]] of subscript ( ,, )and strikeout ( -- ).  Took a couple minutes, can't get superscript to work ( <nowiki>^^</nowiki> ) regardless of sort, always get intercepted as a table.  even updated the toolbar to support the new syntax.  -- //[[brian.andrew@brianandjenny.com|Brian Hartvigsen]] 2008-02-23 13:27//
> I actually got superscript and the new table header syntax working.  The later is probably a dirty hack, but it works ;-) -- //[[brian.andrew@brianandjenny.com|Brian Hartvigsen]] 2008-02-23 13:27//

>> <del>Nice, if you don't mind sharing your work patches are always welcome.</del> Just got the mail :-).  --- //[[chi@chimeric.de|Michael Klier]] 2008-02-24 11:42//