I'd like to propose the following logic for handling this element:

# If the first brace is on the first column, and there are no non-whitespace characters after the last brace, then this element starts a block-level element.
# Otherwise, start a <span>.

The point is that I've found that my users often want to escape markup within a sentence, and the above rules seem to work well in that case.

Whether there is whitespace before the first brace is a matter of taste, I believe.

-- Janne Jalkanen, 31-Aug-2006


like this?
{{{

this is an example {{ ==h1, **bold** }} that starts a span
and this is an example as a block for sourcecode

{{
println 'hello world';
}}

}}}

This way we would not need seperate syntaxes for monospaced and preformatted

-- Christoph, 31-Aug-2006

Well, monospace is different from preformatted which is different from monowiki.  But essentially, yes.

-- JanneJalkanen

I agree with Janne. I'd phrase the rules differently, however:

# If the opening triple braces start on the first column, open a pre block. It is closed by closing triple braces starting on the first column.
# Any other opening triple braces open a span. They are closed by tripple braces.

This has the benefit that you can include the markup for unprocessed text inside the markup for preformatted text. Something I have wanted to do on this wiki several times!

The desired result is:

{{{
To produce bold text, use {​{​{**bold**}​}​}.
}}}

And not:

{{{
To produce bold text, use {{{**bold**}}}.
}}}

-- [AlexSchroeder]

!Collision with MediaWiki format parameters

Unfortunately &#123;&#123;{..&#125;&#125;} for preformatted text collides with MediaWiki template parameters, see [Creole Markup Collision Analysis]. Since MediaWiki is probably the most popular wiki of all this needs to be changed.

-- MartinBudden, 2006-12-28

So a single wiki engine uses markup conflicting with Creole for a feature pretty unique for it. That's unfortunate. What can we do?

Update:
After some reaserach on MediaWiki's templates, I think it's not that bad at all:
* Normal (non-template) pages can use monospaced text without problems
* Template pages can use the preformatted blocks normally
* Template pages can render inline {{{{{{...}} } }}} as nowiki text by default, with two exceptions:
** When there is only a number inside, and the page is being included as a template with at least that number of paramteres
** When there is a parameter name inside, and the page is being included as a template with that named parameter passed

It has two disadvantages:
* makes it harder to explain/understand the creating of templates -- but they are pretty advanced and rare feature anyways
* makes it a little harder to write (and maintain) the parser -- but that's something you do for a single wiki engine -- and at its cost you have a pretty popular and collision-free syntax in Creole. It's not me who is going to do that work, but I think it's worth it.
-- RadomirDopieralski, 2006-12-29

Radomir,

I agree with your comments:
* the use of triple braces for preformatted text complicates the MediaWiki parser, but it is possible
* writing templates is already a specialized skill

I've changed the collision to a partial collision.

-- MartinBudden, 2007-01-01

!Comments about preformatted text

Preformatted text is important for me, and is turning out to be quite tricky for a variety of reasons.

First, I need to handle inline comment enclosed in curly braces (this is a common notation in set theory, like {A, B}). So if I have four open curlies followed by four closes, how do I handle that? One provisional solution I'm considering is associating the extra close curlies with the ''inside'' of the span, so the regex for the closing markup is three closing curlies not followed by a fourth: {{\}\}\}(?!\})}} in Python syntax, for the coders out there. This would also provide an escape for three or more closing curlies inside a span: just follow those with three closing curlies followed by three opening ones, to open a new span.

Second, the 0.3 spec seems to indicate that wiki markup is processed inside the inline preformatted element. That would be a problem, because there's all kinds of stuff that might go in the tag, some of which might look like markup. Block elements clearly do not have their markup processed.

In any case, even if no wiki markup were allowed inside preformatted inline spans, it would be possible to get the bold preformatted effect by reversing the nesting of the markup, putting the bold on the outside and the pre on the inside (as a reminder of how tricky this is, I was not able to get a sample to render correctly in this Wiki engine).

Third, I'm currently using backslash to escape wiki markup (something often done with a <nowiki> tag). This will conflict with the proposed {{\}}{{\}} syntax for linebreaks. My current inclination is to remove it entirely, but that leaves me with no good way to indicate nowiki outside monospaced spans. A workable hack is to intersperse empty preformatted spans to break up what would otherwise be interpreted as markup.

-- [Raph Levien] 31 Dec 2006

For the first of your problems I can see two solutions. If it's only an occassional thing, then you can go with {{{{{{{A,B} ~}}}}}}. The extra space does look weird, but hopefully doesn't have a meaning in math language. The second solution, if the wiki site you use talks about math often, would be to intorudce an additional {{{$$...$$}}} markup (not part of the Creole, but Creole is extensible) for math, that would either use Latex or MathML for formatting, or just typeset the mathematical formulas with a distinct font (and of course escape the markup).

Second, obviously no markup should be interpreted inside "nowiki", except the three closing curly braces, and maybe an escape character, if we will have any. Of course, markup defined outside of the "nowiki" span, like lists, emphasis and tables, is still in effect.

Third, we still don't know what markup to use for the line ends. We are open to suggestions. "\\" is just one common solution, but I'm sure we can do better than that.

Thank you for your feedback, and please remember that Creole is supposed to be a "common part" of wiki markups (or an alternate input method), not necessarily the only markup available -- there are so many different use cases, that this woudn't be possible.

Btw, your idea with the closing curly braces is interesting -- I don't think it breaks anything, and it lets you write {{{{{{{{{...~}}}~}}}}}} without the need for escape characters or spaces -- I doubt anybody would need a "nowiki" span immediatelly followed by a curly brace.

-- RadomirDopieralski, 2006-01-01

One idea would be to extend Creole to have a [heredoc|EnWikipedia:Heredoc] style syntax. That way could vary the terminating token as needed. 

-- JaredWilliams, 2006-01-01

Isn't it a little complicated, and unfortunately, impossible to parse with regexps (ok, it's possible with perl's and python's regexp, by use of the python's {{{(?P=...)}}} for example). What's more, do we need/want to have Creole "complete", in the sense that every (valid) output is possible to achieve?

-- RadomirDopieralski, 2006-01-01

Its just a back reference isn't it? Something like {{{ /{{{(\w+)\n(.*)\n\1/ }}}. 
Obviously most Wiki's probably wouldn't need such a feature, therefore probably shouldn't be in Creole. But also offers a syntax for marking a range of text (if generalised further) to assign an identifier to a section of a page for transclusion.

-- JaredWilliams, 2006-01-01

The extra spaces in Radomir's [CheatSheet] suggest the need for extra escaping logic for three closing braces on a line by itself within a preformatted block. I suggest that one backslash is removed from any line within a preformatted block consisting entirely of one or more backslashes followed by three closing braces. This could be optional in the ExtensibleByOmission sense, to make life easier for implementors of simple Creole engines. In any case the chance of this pattern being an actual collision is near zero. Note also that this pattern is the same as the JSPWiki hosting this page, except that JSPWiki uses tilde instead of backslash. (I don't have a strong feeling about this choice, and could live with tilde)

I was curious how the main page PreformattedAndNowiki implemented the escaping, and found zero-width spaces between the closing braces. This is a rather extreme form of InvisibleMarkup.

I have implemented the suggestion of associating extra curlies to the inside of an inline preformatted block in [Barghest], and am happy with the way it turned out.

-- RaphLevien 2007-01-02

Escape logic is not required for preformatted text if (a) the Creole parser reference counts the number of opening and closing braces inside the block; and (b) the block contains a balance of opening and closing braces. Of course, a) might be difficult to implement in some languages, and b) might not be possible in all cases. Anyhow, it works well for me in Key/C and generally the text I work with has a balance of opening and closing braces, so it's no problem.

I'm hoping to avoid escape sequences in my wiki implementation but perhaps at some point they will become necessary. As a point of interest, I can copy the whole [Creole 0.1 Test Cases] text into my preformatted block without making any changes. It's kind of fun and certainy a good challange for the parser!

For what it's worth, I think the JSPWiki use of tilde for escaping three closing braces is nice and clear.

-- MarkWharton, 2007-01-03

Counting is a possibility, and handles the CheatSheet use case fairly handily, but I think it's not as wiki-like and not quite as general (what if you wanted separate blocks to show the beginning and ending sections?)

I was going to write that because there are a couple of good ways of doing this, it's a good candidate for ExtensibleByOmission, but if the CheatSheet becomes popular, it really would be a good idea to have it work without alterations in most all Creole parsers.

-- RaphLevien 2007-01-02

I'm against special cases in the spec, even if they allow some popular use cases. If we are going to have an escape character, it's best (IMHO) to make it work everywhere the same.

Why not solve the problem of three closing braces the same way
as in the inline nowiki blocks? If there are two (or more) consecutive lines containing only "}}}" in them, make all but the last one of them a part ofthe pre block, and treat the last one as the ending:
{{{
{{{
{{{
   some example
~}}}
~}}}
}}}
this doesn't limit the expressive power of Creole -- if someone __does__ desire to put three closing curly braces right after the pre block, he/she can separate them with a blank line (this introduces an explicit end-of-block instead of the implicit one after the <pre>) and have the expected result:
{{{
{{{
{{{
   some example
~}}}

~}}}
}}}

I don't even think it needs to be mentioned in user cheat sheets -- because that's the __expected__ way it should behave, people will try this first before trying to escape things.

-- RadomirDopieralski, 2007-01-03

Thanks for the suggestions! (I should try thinking about things from a general user point of view ;-) I've implemented a combination of counting the opening curly braces (to monitor the balance) and treating all closing curly braces as terminators. The parser scans backwards to "adjust" whenever any unbalanced closing curly braces are found. It handles most of the weird combinations I put to it with only a few exceptions (like closing curly braces on the first line and opening curly braces on the last line etc.). It's pretty general, however, I've had to add a special case for inline {{{{{{}}} {{{~}}}}}} to include {{{~}}}}}} inside. I do this by checking for {{{~}}}}}} immediately following the first {{{~}}}}}}. It seems to work but probably needs more testing before I can be sure.

-- MarkWharton, 2007-01-06