= Wiki Creole =

[[http://www.wikicreole.org/ | Wiki Creole]] is an attempt to create a compatibility layer between Wikis, by trying to define a kind of common syntax:

 ''Creole is a common wiki markup language to be used across different Wikis. It's not replacing existing markup but instead enabling wiki users to transfer content seamlessly across wikis, and for novice users to contribute more easily.''

While our current Wiki engine doesn't yet allow to implement compatibility with WikiCreole by the way of a plugin, our [WikiFormatting Wiki Syntax] happens to be ''close enough'' to the spec that only small tweaking would be needed to reach a good compatibility level.

As MoinMoin switched to a creole friendlier markup in 1.6 and BitBucket also supports fully the WikiCreole 1.0 spec, the Trac wiki syntax should also become more creole-friendly. !DokuWiki and MediaWiki (two [search:dokuwiki wikis] [search:mediawiki popular] among Trac users) compatibility would also increase in the process as they have a number of similarities with creole. Complete compatibility is probably out of reach, but there are a number of things we can adopt without breaking anything.

== Creole syntax

{{{#!table style="margin:auto"
||= Cheat Sheet for Wiki Creole 1.0 =||
|| [[Image(http://www.wikicreole.org/attach/CheatSheet/creole_cheat_sheet.png)]] ||
}}}

== Details

TODO: add a compatibility column to list some engines that have a compatible syntax

||= Wiki Markup =||= Display =||= Status =||
|------------------------------------------    additional inline formatting:
|| `//italics//` || //italics// || In #4356 ||
|| `**bold**` || **bold** || In #4356 ||
|------------------------------------------    alternate syntax for lists:
{{{#!td
{{{
* Bullet list
* Second item
** Sub item
}}}
}}}
{{{#!td
* Bullet list
* Second item
** Sub item
}}}
{{{#!td
`** Sub item` will conflict with bold;
we therefore really need to parse the structural markup before the inline markup here (see [TracDev/Proposals/VerticalHorizontalParsing vertical/horizontal parsing]).

Likely in [milestone:0.13]
}}}
|------------------------------------------
{{{#!td
{{{
# Numbered list
## Second item
## Sub item
}}}
}}}
{{{#!td
# Numbered list
## Second item
## Sub item
}}}
{{{#!td
No conflict but needs symmetry with the unordered lists.

Likely in [milestone:0.13]
}}}
|------------------------------------------    alternate syntax for links:
|| `Link to [[wikipage]]` ||\
|| Link to [[wikipage]] ||\
{{{#!td
Obvious conflict with the syntax of WikiMacros.
Fix is obvious as well: anything ''not'' recognized as a macro will be linkified in the `wiki:` realm (by default), instead of generating an error.

See also [MoinMoin:HelpOnLinking#Linking].

In #4356
}}}
|------------------------------------------
|| `[[URL|linkname]]` ||\
|| [[URL|linkname]] ||\
|| In #4356 ||
|------------------------------------------    variant for headings:
{{{#!td
{{{
== Large heading
=== Medium heading
==== Small heading
}}}
}}}
{{{#!td style="padding-left: 2em"
== Large heading
=== Medium heading
==== Small heading
}}}
|| In [milestone:0.12] ||
|------------------------------------------     white space:
{{{#!td
{{{
No
linebreak!

Use empty row (sic)
}}}
}}}
{{{#!td
No
linebreak!

Use empty row (sic)
}}}
|| All versions ||
|------------------------------------------
|| `Force\\linebreak` ||\
|| Force\\linebreak ||\
|| In #4356 ||
|------------------------------------------
{{{#!td
{{{
----
Horizontal line
}}}
}}}
{{{#!td
----
Horizontal line
}}}
{{{#!td
Note: for symmetry with `[[br]]` we could have an `[[hr]]` macro 
}}}
|------------------------------------------    alternative to [[Image]] macro:
|| `{{Image.jpg|title}}` ||\
|| {{Image.jpg|title}} ||\
{{{#!td
See also [MoinMoin:HelpOnLinking#Embedding]

Likely in [milestone:0.13]
}}}
|------------------------------------------    variant for pipe-based tables:
{{{#!td
{{{
|=|=table|=header|
|a|table|row|
|b|table|row|
}}}
}}}
{{{#!td
|=|=table|=header|
|a|table|row|
|b|table|row|
}}}
{{{#!td
Nearly the same example works with double pipes:
  {{{
  ||=||=table||=header||
  ||a||table||row||
  ||b||table||row||
  }}}
  {{{#!div
  ||=||=table||=header||
  ||a||table||row||
  ||b||table||row||
  }}}

See #6630 for a plan to support single pipe syntax as well.

Likely in [milestone:0.13]
}}}
|------------------------------------------    blocks:
{{{#!td
  {{{
  {{{
  == [[Nowiki]]:
  //**don't** format//
  }}}
  }}}
}}}
{{{#!td
  {{{
  == [[Nowiki]]:
  //**don't** format//
  }}}
}}}
|| All versions ||
|------------------------------------------

Note also that the creole
[http://www.wikicreole.org/wiki/CreoleAdditions#section-CreoleAdditions-PlugInExtension extension markup],
`<<...>>` is used in MoinMoin as a replacement for the `[[...]]` 
macros (see MoinMoin:HelpOnMacros). 
This is a logical follow-up to their adoption of `[[...]]`
as the primary link syntax.
Though we don't necessarily need to remove that notation for macros (as noted above in the table), we could adopt the `<<...>>` syntax as an alternative. Then we need to unify this with the `<...>` links as well.

Bottom line: we would have `[...]` and `<...>` links, `[[...]]` and `<<...>>` macros or links if there's no corresponding macros. 

The `[...]` form is the most "sensitive" one, as we need to support `[123]` revision links. Therefore it seems fine to make the `realm:` prefix mandatory (or other kinds of specialized prefixes, like `./`, `../`, `/` and `#`, `=#`). The `<...>` form also requires a realm. Conversely, `[[...]]` and `<<...>>` are more "robust" and shouldn't require a realm, though they should accept one if given.

{{{
#!comment
Btw, another TODO for row separators:
{{{
|------------------- <text>
}}}
the <text> should be ignored, or placed in an HTML comment.
}}}

See also:
 * ticket #4356 (will be in [milestone:0.12])
 * [http://www.wikicreole.org/wiki/Creole1.0 Creole 1.0]
 * [http://www.aifb.uni-karlsruhe.de/Publikationen/showPublikation_english?publ_id=1242 WIF]
 * [http://www.wikicreole.org/wiki/TracWiki TracWiki page on WikiCreole] (read-only unfortunately)
 * TracDev/Proposals/AdvancedWikiFormatting
 * [http://trac-hacks.org/wiki/WikiCreoleRendererPlugin Trac plugin which renders WikiCreole as HTML] - "full" WikiCreole compatibility on one side, but on the other side, doesn't support any of the TracLinks or the other Trac specific syntax