(anonymous guest) (logged out)

Copyright (C) by the contributors. Some rights reserved, license BY-SA.

Sponsored by the Wiki Symposium and the Nuveon GmbH.

 

Add new attachment

Only authorized users are allowed to upload new attachments.

List of attachments

Kind Attachment Name Size Version Date Modified Author Change note
txt
wikicreole1.txt 17.5 kB 1 12-Dec-2009 08:59 ChristophSauer

This page (revision-67) was last changed on 25-Feb-2013 09:27 by ChristophSauer  

This page was created on 02-May-2007 18:10 by ChristophSauer

Only authorized users are allowed to rename pages.

Only authorized users are allowed to delete pages.

Difference between version and

At line 1 changed one line
This is the proposed v1.0 spec of Creole (2007-May-09), under discussion until 2007-Jun-13. Also see [[Roadmap to Creole 1.0]], [[Creole 1.0 Poll]] and [[reasoning]] for more information. Note that [[Creole 0.7]] was rejected.
<<ALLOW edit Editor, Admin>>
<<ALLOW view All>>
At line 4 added 22 lines
%%commentbox
[[wikicreole1.txt|Sourcecode of this page]]
[{TableOfContents title='Overview'}]
**Translations**
* [[http://science.webhostinggeeks.com/creole-10|Serbo-Croatian]], translated by Anja Skrba
If you would like to add a translation, contact [[Christoph Sauer]], he will put your link up here.
** Open Wiki Discussions**
The Creole 1.0 project has been successfully finished. Therefore we decided to close down this wiki for editing. If you want to contribute to the next version of creole you can use the new creole wiki at [[http://wiki.wikicreole.org/]].
* [[http://wiki.wikicreole.org/Creole%201.0|Creole 1.0]]
* [[http://wiki.wikicreole.org/Creole%202.0|Creole 2.0]]
%%
This is the final v1.0 spec of Creole (2007-Jul-04) which will be frozen for two years. Also see [[Roadmap to Creole 1.0]], [[Creole 1.0 Poll]] and [[reasoning]] for more information. You can use the [[Creole 1.0 Test Cases]] to check the compliance of your engine implementation.
At line 27 added one line
* whitespace allowed before all elements except nowiki blocks
At line 9 changed one line
* removed escaping nowiki/preformatted because this is now covered by the escape character
* a tilde in front of a URL should prevent it from becoming a link
At line 11 removed 2 lines
[{TableOfContents title='Overview'}]
At line 30 changed one line
**Reasoning:** A star ({{{*}}}) is the most used symbol to emphasize text online. Double symbols are generally used in Creole to avoid accidentally parsing text not meant to be parsed. [[Bold and Italics Reasoning|More details]]
**Rationale:** A star ({{{*}}}) is the most used symbol to emphasize text online. Double symbols are generally used in Creole to avoid accidentally parsing text not meant to be parsed. [[Bold and Italics Reasoning|More details]]
At line 34 changed one line
Ignore // for italics processing if immediately following ''http:'' or ''ftp:''
Ignore {{{ // }}} for italics processing if immediately following {{{ http: }}} or {{{ ftp: }}}
At line 45 changed one line
**Reasoning:** A slash ({{{/}}}) looks like slanted italics, so it is intuitive and thus easier to remember. [[Bold and Italics Reasoning|More details]]
**Rationale:** A slash ({{{/}}}) looks like slanted italics, so it is intuitive and thus easier to remember. [[Bold and Italics Reasoning|More details]]
At line 64 changed one line
But, should //not be...
But, should <em>not be...</em>
At line 67 changed one line
...able// to cross paragraphs.
...able<em> to cross paragraphs.</em>
At line 73 changed 2 lines
Bold and italics should ''be\\
able'' to cross lines.
Bold and italics should //be\\
able// to cross lines.
At line 107 removed 61 lines
== Lists
Bold, italics, links, nowiki can be used in list items, but they cannot span several list items. Whitespace is optional before and after the * or # characters, however a space is required afterwards if someone wishes to start a list element with bold text. A list element ends at the end of a line, although it can contain line breaks forced with {{{\\}}}. It is recommended to have support for a depth of at least five levels of nesting. Any line that does not start with a {{{*}}} or {{{#}}} (optionally preceded with some whitespace) ends the list.
**About unordered lists and bold:** a line starting with {{{**}}} (including optional whitespace before and afterwards), immediately following any list element on a line above, will be treated as a nested unordered list element. Otherwise it will be treated as the beginning of bold text. Also note that bold and/or italics cannot span lines in a list.
=== Unordered Lists
Creole:
{{{
* Item 1
** Item 1.1
* Item 2
}}}
Recommended XHTML:
{{{
<ul>
<li>Item 1
<ul>
<li>Item 1.1</li>
</ul>
</li>
<li>Item 2</li>
</ul>
}}}
Sample Output:
* Item 1
** Item 1.1
* Item 2
**Reasoning:** A large majority of wiki engines use an asterisk ({{{*}}}) to denote bullet lists. The multiple asterisk approach for sublists was the first wiki syntax for sublists. Users do not need to count leading spaces like in markups where a sublist level is determined by the number of its leading spaces. [[Lists Reasoning|More details]]
=== Ordered Lists
Creole:
{{{
# Item 1
## Item 1.1
# Item 2
}}}
Recommended XHTML:
{{{
<ol>
<li>Item 1
<ol>
<li>Item 1.1</li>
</ol>
</li>
<li>Item 2</li>
</ol>
}}}
Sample Output:
# Item 1
## Item 1.1
# Item 2
**Reasoning: ** The number sign ({{{#}}}) is used for ordered lists in most wikis. [[Lists Reasoning|More details]]
At line 170 changed one line
Only three different sized levels of headings are required. Closing (right-side) equal signs are optional, don't need to be balanced and don't impact the kind of heading generated. Whitespace is not allowed before the left-side equal signs. Only whitespace characters are permitted after the closing equal signs. No markup has to be parsed within headings.
Only three different sized levels of headings are required. Closing (right-side) equal signs are optional, don't need to be balanced and don't impact the kind of heading generated. Whitespace **is** allowed before the left-side equal signs. Only whitespace characters are permitted after the closing equal signs. Markup parsing is optional within headings.
At line 174 changed one line
= Level 1 (largest) =
== Level 1 (largest) =
At line 200 changed one line
**Reasoning:** Using equal signs ({{{=}}}) is the most popular wiki header markup. Since there are more equal signs for smaller headers, subheaders will become more indented making it easier to get a visual overview from the markup alone. Closing equal signs are optional, making Creole more flexible since many wiki engines do not require them. [[Headings Reasoning|More details]]
**Rationale:** Using equal signs ({{{=}}}) is the most popular wiki header markup. Since there are more equal signs for smaller headers, subheaders will become more indented making it easier to get a visual overview from the markup alone. Closing equal signs are optional, making Creole more flexible since many wiki engines do not require them. [[Headings Reasoning|More details]]
At line 206 changed one line
Free-standing urls should be detected and turned into links. Single punctuation characters ({{{,.?!:;"'}}}) at the end of urls should not be considered part of the url.
Free-standing URLs should be detected and turned into links. Single punctuation characters ({{{,.?!:;"'}}}) at the end of URLs should not be considered part of the URL.
At line 242 changed one line
**Reasoning:** Almost all wikis use square brackets ({{{[[]]}}}) to make links. Using double square brackets allows single square brackets to be used freely without worry of turning them into links. [[Links Reasoning|More details]]
**Rationale:** Almost all wikis use square brackets ({{{[[]]}}}) to make links. Using double square brackets allows single square brackets to be used freely without worry of turning them into links. [[Links Reasoning|More details]]
At line 247 changed one line
A list, table or preformatted block end paragraphs too.
A list, table or nowiki block end paragraphs too.
At line 268 changed one line
**Reasoning:** No markup tags should be necessary to start a new paragraph. [[Paragraphs and Line Breaks Reasoning|More details]]
**Rationale:** No markup tags should be necessary to start a new paragraph. [[Paragraphs and Line Breaks Reasoning|More details]]
At line 290 changed 22 lines
Creole:
{{{
* This is a single list item
followed by a paragraph?
}}}
Recommended XHTML:
{{{
<ul>
<li>This is a single list item</li>
</ul>
<p>
followed by a paragraph
</p>
}}}
Sample Output:
* This is a single list item
followed by a paragraph
**Reasoning: ** __blog-style vs. wiki-style__\\
**Rationale: ** __blog-style vs. wiki-style__\\
At line 316 changed one line
== Nowiki (Preformatted)
== Lists
At line 318 changed one line
This works inline or as a block. __No wiki markup is interpreted between these characters.__ As a block, the three curly braces should be on one line by itself to open and another line of three curly braces should be on a line by itself to close. In a block, characters are displayed in monospace. For inline nowiki text, wiki implementers can decide whether to display this text regularly or in monospace.
List items begin with a {{{*}}} or a {{{#}}} at the beginning of a line. Whitespace is optional before and after the {{{*}}} or {{{#}}} characters, however a space is required afterwards if the list element starts with bold text. A list item ends at the line which begins with a {{{*}}} or {{{#}}} character (next item or sublist), blank line, heading, table, or nowiki block; like paragraphs, it can span multiple lines and contain line breaks forced with {{{\\}}}. It is recommended to have support for a depth of at least five levels of nesting. Bold, italics, links, and nowiki can be used in list items, but they cannot span several list items.
At line 320 changed one line
**Note:** if you need a more general purpose escape character, please see [[Additions]].
**About unordered lists and bold:** a line starting with {{{**}}} (including optional whitespace before and afterwards), immediately following any list element on a line above, will be treated as a nested unordered list element. Otherwise it will be treated as the beginning of bold text.
At line 262 added 2 lines
=== Unordered Lists
At line 324 changed 3 lines
{{{
//This// does **not** get [[formatted]]
~}}}
* Item 1
** Item 1.1
* Item 2
At line 331 changed 3 lines
<pre>
//This// does **not** get [[formatted]]
</pre>
<ul>
<li>Item 1
<ul>
<li>Item 1.1</li>
</ul>
</li>
<li>Item 2</li>
</ul>
At line 337 changed 3 lines
{{{
//This// does **not** get [[formatted]]
}}}
* Item 1
** Item 1.1
* Item 2
At line 288 added 4 lines
**Rationale:** A large majority of wiki engines use an asterisk ({{{*}}}) to denote bullet lists. The multiple asterisk approach for sublists was the first wiki syntax for sublists. Users do not need to count leading spaces like in markups where a sublist level is determined by the number of its leading spaces. Optional leading spaces can be used to make the Creole markup clearer if the author wishes so. [[Lists Reasoning|More details]]
=== Ordered Lists
At line 343 changed one line
Some examples of markup are: {{{** <i>this</i> ** ~}}}
# Item 1
## Item 1.1
# Item 2
At line 348 changed one line
Some examples of markup are: <tt>** &lt;i&gt;this&lt;/i&gt; **</tt>
<ol>
<li>Item 1
<ol>
<li>Item 1.1</li>
</ol>
</li>
<li>Item 2</li>
</ol>
At line 351 changed one line
Sample output:
Sample Output:
# Item 1
## Item 1.1
# Item 2
At line 353 changed one line
Some examples of markup are: {{{** <i>this</i> **}}}
**Rationale: ** The number sign ({{{#}}}) is used for ordered lists in most wikis. [[Lists Reasoning|More details]]
At line 355 removed 2 lines
**Reasoning: ** There must be a way for users to enter text which will not be formatted by the wiki engine. Triple curly brackets ({{{{{{~}}}}}}) were chosen due to their visibility and unlikeliness to be in the "code" itself. [[Preformatted and Nowiki Reasoning|More details]]
At line 366 changed one line
**Reasoning:** All non-WYSIWYG wikis use hyphens ({{{----}}}) to denote horizontal rules. Most wikis require four. [[Horizontal Rule Reasoning|More details]]
**Rationale:** All non-WYSIWYG wikis use hyphens ({{{----}}}) to denote horizontal rules. Most wikis require four. [[Horizontal Rule Reasoning|More details]]
At line 374 changed one line
{{{ <img src="myimage.png" alt="this is my image"/> }}}
{{{ <img src="myimage.png" alt="this is my image" /> }}}
At line 376 changed one line
**Reasoning:** The most common image markup was double curly brackets ({{{ {{}} }}}) which will then have the same internal structure as links for consistency. [[Images Reasoning|More details]]
**Rationale:** The most common image markup was double curly brackets ({{{ {{}} }}}) which will then have the same internal structure as links for consistency. [[Images Reasoning|More details]]
At line 380 changed one line
All cells are separated by single pipes. The ending pipe is optional. You can embed links, bold, italics, monospace, line breaks and preformatted/nowiki in table cells. Equal sign directly following pipe defines a header. Headers can be arranged horizontally or vertically. Comparison details found on [List Of Table Markups]
All cells are separated by single pipes. Leading spaces are permitted before the first cell of a row and trailing spaces are permitted at the end of a line. The ending pipe is optional. You can embed links, bold, italics, line breaks, and nowiki in table cells. Equal sign directly following pipe defines a header. Headers can be arranged horizontally or vertically. Comparison details found on [List Of Table Markups]
At line 398 changed one line
<td>Two lines\\in Cell 1.2</td>
<td>Two lines<br />in Cell 1.2</td>
At line 412 changed one line
**Reasoning:** Most wikis use single or double pipes to separate table cells. Single pipes ({{{|}}}) allow better use of space and are faster to type than double pipes since pipes are not usually needed in table cells. [[Tables Reasoning|More details]]
**Rationale:** Most wikis use single or double pipes to separate table cells. Single pipes ({{{|}}}) allow better use of space and are faster to type than double pipes since pipes are not usually needed in table cells. [[Tables Reasoning|More details]]
At line 414 changed one line
== Placeholder
== Nowiki (Preformatted)
At line 416 changed one line
When there is something advanced, a placeholder will show up, so users will not be confused seeing more than one syntax. (optional for wiki developers)
This works inline or as a block. **No wiki markup is interpreted between these characters**, even tildes which are used as escape characters elsewhere (see below). As a block, the three curly braces should be on one line by itself to open and another line of three curly braces should be on a line by itself to close, without leading spaces. In a block, characters are displayed in monospace. For inline nowiki text, wiki implementers can decide whether to display this text regularly or in monospace.
At line 418 removed 2 lines
**Note:** do not confuse this with the plug-in syntax which can be found at [[Additions]].
At line 421 changed one line
{{{ <<<x>>> }}}
{{{
{{{
//This// does **not** get [[formatted]]
~}}}
}}}
At line 423 changed 8 lines
**Reasoning:** This is the only new markup introduced in Creole. This was mainly developed due to MediaWiki's extensive use of special characters making it practically impossible to implement Mixed Creole mode. Few wikis use angle brackets ({{{<<<>>>}}}) for markup. This markup is generated by the wiki engine rather then typed in by the user, therefore we use three instead of two markup characters to reserve the markup with two angle brackets for extension elements that are typed in by users. [[Placeholder Reasoning|More details]].
==Escape Character
It is often troublesome to use the nowiki in-line to display symbols of wiki syntax, so it would be useful to have an escape character that could be put before wiki syntax to prevent it from being interpreted. The tilde was chosen not to conflict with line breaks and because it is a very infrequently used character. It is not generally easy to type, but it will also not need to be used often, so in this sense it is also suitable.
The escape character only escapes the character immediately following it. This means that e.g. the tilde in this use case is displayed as tilde and not escaped. It would certainly **never** escape if followed by a space or an alphanumeric character. However, if a wiki uses CamelCase, it is recommended that a tilde in front of a CamelCased phrase keep it from becoming a link.
Recommended XHTML:
At line 432 changed one line
http://stud.hs-heilbronn.de/~someone
<pre>
//This// does **not** get [[formatted]]
</pre>
At line 435 changed 2 lines
Escape characters only trigger if you use it in combination with a character that has special meaning in creole and would otherwise be rendered as markup. For example if you use "tilde + equal sign as first characters in a line" it will escape the equal sign and display it as such because otherwise it would be rendered as heading.
Sample Output:
At line 438 changed 3 lines
=Heading
~=Line starting with equal sign, this displays a normal tilde: ~
~=~=~= Line starting with three equal signs
//This// does **not** get [[formatted]]
At line 443 changed 2 lines
If an escape character is only used in certain combinations we have a minimum of collisions with existing markup. For example if an wiki uses tilde as normal markup, it would not collide with e.g.
Creole:
At line 446 changed 3 lines
~=This is a heading
~this is subscript in certain wikis~
~~=This is a sentence with a tilde and an equal sign at the beginning... (tilde escapes itself)
Some examples of markup are: {{{** <i>this</i> ** ~}}}
At line 451 changed 2 lines
Here's a complete list that would cause the escape character (e.g. tilde) to trigger escaping of the following character combinations. This can be extended as need be. Note also that an escape character can be escaped by putting a space after it, since a space cannot be escaped.
Recommended XHTML:
At line 454 changed 20 lines
Escapes Markup Example:
============== ========
Bold ~*~*
Italics ~/~/
Unordered Lists ~-
Ordered Lists ~#
Headings ~=
Links Open ~[~[
Inside Links [[A pipe ~| is used within links]]
Links Close ~]~]
Line Breaks ~\~\
Horizontal Line ~-~-~-~-
Image Open ~{~{
Image Close ~}~}
Table Open ~| this is | not a table
Inside Tables | x~|y |
Escaping Escape ~~
Escaping Escape ~<space>
Nowiki Open ~{~{~{
Nowiki Close ~}~}~}
Some examples of markup are: <tt>** &lt;i&gt;this&lt;/i&gt; **</tt>
At line 476 changed one line
So, for example, this markup:
Sample output:
At line 410 added 11 lines
Some examples of markup are: {{{** <i>this</i> **}}}
===Closing braces in nowiki
To include closing braces where they might be considered as nowiki or preformatted end tag, there are two additional rules:
* In inline nowiki, any trailing closing brace is included in the nowiki span (i.e. in a sequence of more than three closing braces, the end marker is made of the //last three braces//).
* In preformatted blocks, since markers must not be preceded by leading spaces, lines with three closing braces which belong to the preformatted block must follow at least one space. In the rendered output, one leading space is removed.
Creole:
Inline nowiki with closing braces: {{{{{if (a>b) { b = a; ~}}}}}}.
Preformatted block with a line containing three closing braces:
At line 480 changed 5 lines
int main(int argc, char *argv[]) {
if argc>0 {
if argc<=1 {
--argc;
~}~}~}
if (x != NULL) {
for (i = 0; i < size; i++) {
if (x[i] > 0) {
x[i]--;
~}}}
At line 488 changed one line
will produce this result:
**Rationale: ** There must be a way for users to enter text which will not be formatted by the wiki engine. Triple curly brackets ({{{{{{~}}}}}}) were chosen due to their visibility and unlikeliness to be in the "code" itself. [[Preformatted and Nowiki Reasoning|More details]]; see also [[Add No Wiki Escape Proposal]].
At line 433 added 8 lines
==Escape Character
The escape character is the tilde (~~). Outside nowiki, preformatted, and URL, the escape character only escapes the character immediately following it, provided that it is not a blank (space or line feed). The following character is rendered as is and cannot be a part of any Creole markup.
The escape character disables the automatic conversion of the URL immediately following to links, and any similar mechanism supported by the wiki engine (camelcase wikiwords, copyright sign, etc.)
Example code:
At line 491 changed 7 lines
<pre>
int main(int argc, char *argv[]) {
if argc>0 {
if argc<=1 {
--argc;
~}}}
</pre>
~#1
http://www.foo.com/~bar/
~http://www.foo.com/
CamelCaseLink
~CamelCaseLink
At line 500 changed one line
**Reasoning:** Users should be able to escape markup characters (or all non-alphanumeric characters) with a special character. It's often faster to type and more readable than using nowiki (3+3 curly braces). In order to allow spaces in front of lists, which is a quite common practice in wiki engines, it should be a escape character other than space. This way, stars, slashes and other markup characters, when found in the original text, can be easily escaped, to be rendered as themselves. [[Escape Character Reasoning|Reasoning]]
Example output:
At line 451 added 19 lines
~#1 \\
http://www.foo.com/~bar/ \\
~http://www.foo.com/ \\
CamelCaseLink \\
~CamelCaseLink
**Rationale:** If one needs keyboard characters often in a text, there would be too many distracting triple curly braces to be able to work with the text well. Therefore an escape character would help to keep people from being so distracted by the nowiki inline and escape character could be used instead. The tilde was chosen, so it would not conflict with the backslashes in line breaks and because it is a relatively infrequently used character. It is not generally easy to type, but it will also not need to be used often, so in this sense it is also suitable. This way, stars, slashes and other markup characters, when found in the original text, can be easily escaped to be rendered as themselves. [[Escape Character Reasoning|Reasoning]]
== Placeholder
When there is something advanced, a placeholder will show up, so users will not be confused seeing more than one syntax. (optional for wiki developers)
**Note:** do not confuse this with the plug-in syntax which can be found at [[Additions]].
Creole:
{{{ <<<x>>> }}}
**Rationale:** This was mainly developed due to MediaWiki's extensive use of special characters making it practically impossible to implement Mixed Creole mode. Few wikis use angle brackets ({{{<<<>>>}}}) for markup. This markup is generated by the wiki engine rather then typed in by the user, therefore we use three instead of two markup characters to reserve the markup with two angle brackets for extension elements that are typed in by users. [[Placeholder Reasoning|More details]].
Version Date Modified Size Author Changes ... Change note
67 25-Feb-2013 09:27 18.19 kB ChristophSauer to previous
66 25-Feb-2013 09:26 18.222 kB ChristophSauer to previous | to last
65 25-Feb-2013 09:25 18.225 kB ChristophSauer to previous | to last
64 25-Feb-2013 09:20 18.2 kB ChristophSauer to previous | to last
63 25-Feb-2013 09:19 17.959 kB ChristophSauer to previous | to last
62 25-Feb-2013 09:18 17.961 kB ChristophSauer to previous | to last
61 25-Feb-2013 09:17 17.884 kB ChristophSauer to previous | to last
« This page (revision-67) was last changed on 25-Feb-2013 09:27 by ChristophSauer