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

---- plugin ----
description: Creole Markup for DokuWiki
author     : Dokufreaks (previous authors: Gina Häußge, Michael Klier, Esther Brunner)
email      : freaks@dokuwiki.org
type       : syntax
lastupdate : 2020-12-13
compatible : !Frusterick Manners, !Greebo, Hogfather, Igor, Jack Jackrum, Kaos
depends    : 
conflicts  : 
similar    : 
tags       : formatting, markup_language, headings, lists

downloadurl: https://github.com/dokufreaks/plugin-creole/zipball/master
sourcerepo:  https://github.com/dokufreaks/plugin-creole
bugtracker:  https://github.com/dokufreaks/plugin-creole/issues
----

===== Description =====

[[http://www.wikicreole.org/|Creole]] is an initiative to bring a common basic set of wiki markup to different wiki engines. The [[http://www.wikicreole.org/wiki/Creole1.0|Creole 1.0 Specs]] (2007-07-04) are very close to the [[:wiki:syntax]] used by DokuWiki. Only those elements differ:

  * [[#Listblock]]
  * [[#Reverse Headings]]
  * [[#Linebreaks]] (dokuwiki linebreaks are correct in creole 1.0)
  * [[#Preformatted]]
  * [[#Tables]] (optional ending pipe not yet supported -- I'm working on a new version)
  * [[#Subscript]] (since Creole 1.0, see http://www.wikicreole.org/wiki/CreoleAdditions)
  * [[#Superscript]] (since Creole 1.0, see http://www.wikicreole.org/wiki/CreoleAdditions)
  * [[#Monospace]] (since Creole 1.0, see http://www.wikicreole.org/wiki/CreoleAdditions)

This 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

===== Installation =====

To install the Creole plugin

  * Go to the Admin page and then [[plugin:extension|Extension Manager]]
  * Search for the plugin "Creole" at the ''Search and Install'' tab
  * Use the ''Install'' button

In the Configuration Settings you can change the Markup precedence over the DokuWiki syntax if you like.

:!: Since release 2020-08-21 the creole plugin is incompatible with DokuWiki release Greebo and the releases before it. If you are using DokuWiki releases before Hogfather then the latest compatible release is [[https://github.com/dokufreaks/plugin-creole/archive/2019-02-06.zip|2019-02-06]]. :!:

===== 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


==== Reverse 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 you 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 and Creole 1.0 do not care about (single) line breaks. Creole 0.3, 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!

Previous versions of this plugin matched Creole 0.3 and so linebreaks were kept as linebreaks. From now on, linebreaks will be replaced by whitespace to match Creole 1.0. The config option ''linebreak'' can be set to ''Linebreak'' to switch back to the Creole 0.3 behaviour and keep the linebreaks.

==== 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.

==== Subscript ====

Creole:

<code>
This is ,,subscripted,, text.
</code>

Output:

This is <sub>subscripted</sub> text.

==== Superscript ====

Creole:

<code>
This is ^^superscripted^^ text.
</code>

Output:

This is <sup>superscripted</sup> text.


==== Monospace ====

Creole:

<code>
This is ##monospace## text.
</code>

Output:

This is ''monospace'' text.

===== Bugs / Feature Requests =====

Please report bugs or feature requests at the [[https://github.com/dokufreaks/plugin-creole/issues|Bug tracker]].

===== Further Resources =====

  * [[https://github.com/dokufreaks/plugin-creole/tree/master|Git Repository]]
  * [[https://github.com/dokufreaks/plugin-creole/issues|Bug Tracker]]

===== Changes =====

{{rss>https://github.com/dokufreaks/plugin-creole/commits/master.atom date}}

===== Todo =====

  * make toolbar work
  * update to Creole 1.0 specs (work in progress)
  * <del>...but there must be a conf option to change linebreaks between Creole 0.3 and 1.0.</del> Done.

===== 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 occurrence 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 all, 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 built-in wiki pages in ''/inc/lang/''.  --- //[[unixprog@gmail.com|konstantin baierer]] 2007-03-31 22:27//

I couldn't resist re-writing that Perl script into a one-liner command (for Mac or Linux - Windows would need different quoting) with a single regex. Admittedly, it's less readable than Konstantin's script, but I like the single formula to revert the number of "''=''". The ''-i.bak'' option makes it do the replacements in-place, saving the original with a .bak extension.
<code bash>
perl -i.bak -pe 's/^(={2,6})(.*?)\1/"="x(2+abs(length($1)-6)).$2/e' YOUR_ORIGINAL_FILE.txt
</code> 
To do it on a whole folder (but be sure to be in the right folder!):
<code bash>
perl -i.bak -pe 's/^(={2,6})(.*?)\1/"="x(2+abs(length($1)-6)).$2/e' *.txt
</code> 
Or by searching, also in subfolders:
<code bash>
find /path/to/wiki/data/pages -type f -name "*.txt" -exec perl -i.bak -pe 's/^(={2,6})(.*?)\1/"="x(2+abs(length($1)-6)).$2/e' "{}" \;
</code> 
--- [[user>Albert25|Albert25]] //2019-09-24 18:24//

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//

There is a problem with the parser. An expression like <nowiki>//italics// = italics</nowiki> is misinterpreted and starts a new chapter section! --- //Morten Nielsen 2009-02-17 14:41//

Also, a new chapter is started when you try to put a double-stroked right arrow (=>, <nowiki>=></nowiki>) at the Beginning of a line. --- //Benjamin Molitor 2009-03-15 09:53//

Creole 1.0 has already been out, any plan to update this plugin to support it?  --- //DAY 2010-01-22 14:18//

To make '|=' working (table heading),I directly edited two files of dokuwiki like below.  Can anyone include these to creole plugin??   --- //[[dryoo@live.cvom|goldseed]] 2010/09/05 10:56//

parser.php line 434
<code php>
//-------------------------------------------------------------------
class Doku_Parser_Mode_table extends Doku_Parser_Mode {

    function Doku_Parser_Mode_table() {
        global $PARSER_MODES;

        $this->allowedModes = array_merge (
                $PARSER_MODES['formatting'],
                $PARSER_MODES['substition'],
                $PARSER_MODES['disabled'],
                $PARSER_MODES['protected']
            );
    }

    function connectTo($mode) {
        $this->Lexer->addEntryPattern('\n\^',$mode,'table');
		$this->Lexer->addEntryPattern('\n\|=',$mode,'table');  // changed!!!
        $this->Lexer->addEntryPattern('\n\|',$mode,'table');
    }

    function postConnect() {
        $this->Lexer->addPattern('\n\^','table');
		$this->Lexer->addPattern('\n\|=','table');  // changed!!!
        $this->Lexer->addPattern('\n\|','table');
        $this->Lexer->addPattern('[\t ]*:::[\t ]*(?=[\|\^])','table');
        $this->Lexer->addPattern('[\t ]+','table');
        $this->Lexer->addPattern('\^','table');
		$this->Lexer->addPattern('\|=','table');  // changed!!!
        $this->Lexer->addPattern('\|','table');
        $this->Lexer->addExitPattern('\n','table');
    }

    function getSort() {
        return 60;
    }
}
</code>

handler.php starting line 578
<code php>
     function table($match, $state, $pos) {
        switch ( $state ) {

            case DOKU_LEXER_ENTER:

                $ReWriter = & new Doku_Handler_Table($this->CallWriter);
                $this->CallWriter = & $ReWriter;

                $this->_addCall('table_start', array(), $pos);
                if ( (trim($match) == '^') or (trim($match) == '|=') ) { // changed!
                    $this->_addCall('tableheader', array(), $pos);
                } else {
                    $this->_addCall('tablecell', array(), $pos);
                }
            break;

            case DOKU_LEXER_EXIT:
                $this->_addCall('table_end', array(), $pos);
                $this->CallWriter->process();
                $ReWriter = & $this->CallWriter;
                $this->CallWriter = & $ReWriter->CallWriter;
            break;

            case DOKU_LEXER_UNMATCHED:
                if ( trim($match) != '' ) {
                    $this->_addCall('cdata',array($match), $pos);
                }
            break;

            case DOKU_LEXER_MATCHED:
                if ( $match == ' ' ){
                    $this->_addCall('cdata', array($match), $pos);
                } else if ( preg_match('/:::/',$match) ) {
                    $this->_addCall('rowspan', array($match), $pos);
                } else if ( preg_match('/\t+/',$match) ) {
                    $this->_addCall('table_align', array($match), $pos);
                } else if ( preg_match('/ {2,}/',$match) ) {
                    $this->_addCall('table_align', array($match), $pos);
                } else if ( $match == "\n|" ) {
                    $this->_addCall('table_row', array(), $pos);
                    $this->_addCall('tablecell', array(), $pos);
                } else if ( $match == "\n^" ) {
                    $this->_addCall('table_row', array(), $pos);
                    $this->_addCall('tableheader', array(), $pos);
                } else if ( $match == '|' ) {
                    $this->_addCall('tablecell', array(), $pos);
                } else if ( $match == '^' ) {
                    $this->_addCall('tableheader', array(), $pos);
		}  else if ( $match == '|=' ) {       // changed!
                    $this->_addCall('tableheader', array(), $pos);
                }
            break;
        }
        return true;
    }
</code>

Has problem with dokuwiki-2010-11-07.tgz “Anteater”. Is there anyone can fix it? 
> Problem is fixed in current version. --- //Benjamin Molitor 2010-12-04 18:07//

----

I haven't account at Github, so I will write here, sorry.

I found a little bug: There is something wrong when I type: %%=>%%

It should be rendered as an arrow mark (=>), but with this plugin i've got something like this (HTML preview):
<code><h1><a name="section" id="section">&gt;</a></h1></code>
You can see it e.g. at the [[wiki:syntax#text_to_html_conversions|syntax]] page with this plugin installed, even if dokuwiki syntax precedence is enabled.

 --- //[[orinoco]] 2011-03-05 19:50//

----

A big thank you to all of you who have created and maintained this plugin. It provides me interoperability with WordPress where I use the BlogText Creole markup plugin. I have enhanced the Creole DokuWiki code running on my computer and would like to share what I have done. Perhaps what I have done, or something like it, could become a part of the standard release.

I enhanced the plugin to support this sort of syntax that I often use (example):
<code>
Host file setup:
# **Desktop Link to Hosts File.** Log in as the Administrator OS user, bring up a Cygwin command window to create a link to the hosts file using the following commands: {{{
cd /cygdrive/c/Users/Administrator/Desktop/

ln -T /cygdrive/c/Windows/System32/drivers/etc/hosts hosts.txt
}}}
# **Add Mac host to hosts file.** Still logged in as the Administrator OS user, add the following line to the hosts file using the hosts.txt desktop link: {{{
10.180.15.2	mymac
}}}
</code>

I enhanced the plugin to switch to block mode for an inline nowiki section that ends with three braces immediately after a newline. Regular inline mode takes precedence - the switch to block mode only happens if there is no normal (i.e., not right after a newline) set of end braces.

Here are the changes:

(1) In preinline.php, only match entry if there is no newline before the terminating braces - I added the [^\n] construct. Here is the connectTo function with that small change:
<code>
    function connectTo($mode) {
        // swg added check for not newline character (not block mode)
        $this->Lexer->addEntryPattern(
                '\{\{\{(?=.*?[^\n]\}\}\})',
                $mode,
                'plugin_creole_preinline'
                );
    }
</code>

(2) Added a second preinline class file, called preinline2.php, for catching the case of an inline nowiki section with a block terminator. Here is the entire file contents:
<code>
<?php
/**
 * Creole Plugin, inline preformatted component: Creole style preformatted text
 * 
 * @license    GPL 2 (http://www.gnu.org/licenses/gpl.html)
 * @author     Esther Brunner <wikidesign@gmail.com>
 */

// must be run within Dokuwiki
if(!defined('DOKU_INC')) die();

if(!defined('DOKU_PLUGIN')) define('DOKU_PLUGIN',DOKU_INC.'lib/plugins/');
require_once(DOKU_PLUGIN.'syntax.php');

/**
 * All DokuWiki plugins to extend the parser/rendering mechanism
 * need to inherit from this class
 */
class syntax_plugin_creole_preinline2 extends DokuWiki_Syntax_Plugin {

    function getInfo() {
        return array(
                'author' => 'Gina Häußge, Michael Klier, Esther Brunner, Sam Gabriel',
                'email'  => 'sam_gabriel@yahoo.com',
                'date'   => '2012-08-17',
                'name'   => 'Creole Plugin, inline preformatted component',
                'desc'   => 'Creole style preformatted text',
                'url'    => 'http://wiki.splitbrain.org/plugin:creole',
                );
    }

    function getType() { return 'protected'; }
    function getSort() { return 103; }

    function connectTo($mode) {
    	// swg added check for newline indicating block mode
        $this->Lexer->addEntryPattern(
                '\{\{\{(?=.*?\n\}\}\})',
                $mode,
                'plugin_creole_preinline2'
                );
    }

    function postConnect() {
        // swg added newline
        $this->Lexer->addExitPattern(
                '\n\}\}\}',
                'plugin_creole_preinline2'
                );
    }

    function handle($match, $state, $pos, &$handler) {
        switch ($state) {
            case DOKU_LEXER_ENTER:
                $handler->_addCall('monospace_open', array(), $pos);
                break;
            case DOKU_LEXER_UNMATCHED:
                // swg changed unformatted to preformatted
                $handler->_addCall('preformatted', array($match), $pos);
                break;
            case DOKU_LEXER_EXIT:
                $handler->_addCall('monospace_close', array(), $pos);
                break;
        }
        return true;
    }

    function render($mode, &$renderer, $data) {
        return true;
    }
}
// vim:ts=4:sw=4:et:enc=utf-8:
</code>

--- //[[sam_gabriel@yahoo.com|Sam Gabriel]] 2012-08-17 22:29//


==== Creole conflicts with fckglite ====
I just learned the hard way, that the creole plugin conflicts with the wysiwyg editor plugin fckglite. If creole is installed, fckglite refuses to save. Depending on circumstance, the section to be edited gets deleted. There are no error messages in /var/log/apache/error.log . Apparently, creole does not even have to be enabled to produce this failures. //[[kmk@iqo.uni-hannover.de|kmk]] 2012-09-17 20:05//
> Solution: http://www.freelists.org/post/fckglite/fckglite-conflicts-with-some-syntax-plugins-Creole. 

>The needed include file for above solution:
<file php isfckgLiteOn.inc>
<?php
function fckgLiteOn() {
 
if(isset($_COOKIE ['FCK_NmSp']) && isset($_COOKIE ['FCKW_USE'])) {
   return false;
}
return true;

}
</file>
 --- [[user>turnermm|Myron Turner]] //2012/09/21 16:57//