.
I have been thinking more about escape. I have started leaning towards the "Escape character should be core" idea (in conjunction with "Escape character should escape a single character" and "Escape character should be ~"). I think it fits well with any future expansion of Creole. However, my real concern is what to do with preformatted block content and external links containing escape characters which are not rendered in the final output. For me, escaping whole Creole markup sequences is not a broad enough solution and imposes hidden constraints and limits future expansion. It was an excellent idea, but I don't believe it's the right way to go. Either we have all or we have nothing.
In the meantime, the simple escape mechanism proposed here for preformatted blocks, I believe, is both adequate and safe. If we don't end up with an escape character then this is the best alternative, without a doubt. Having said that, I will endeavour to work through my escape thinking over the next few weeks and input into any escape arguments.
MarkWharton 2007-05-10
We changed the two angle brackets to three angle brackets, to make it easier to write plugin syntax (see GenericExtensionElementProposal, BlockMarkupNotionCriticism). Placeholder syntax is generated by the wiki engine, while plugin syntax has to be written by users. I think this last small change will not influence any implementation since nobody uses placeholders so far, and on the other hand will make it easier to evolve creole additions in a way that is consistent with the goals of fast to type and readable markup.
-- ChristophSauer, 2007-Jun-01 15:54 (CEST)
The escape character should become part of the core Creole 1.0. Adding a simple and generic escaping rule now isn't that big deal. However, adding it later (or make it optional) will cause some headaches I think...
-- OliverHorn 2007-06-05
I agree. With you now we have a majority ;-) Let's add it. Let's replace Creole1.0#section-Creole1.0-EscapingPreformattedNowiki with the more generic escape character rule from Creole Additions. Radomir? Yves?
-- ChristophSauer, 2007-Jun-06 10:19 (CEST)
I still don't like having an escape character. If we must have one, however, I prefer Radomir's mechanics, as explained on Talk.Escape Character Decision.
Yes, I still agree with an escape character in Creole Core which escapes the next non-alphanumeric character only, everywhere but in inline nowiki and block preformatted. Wrt Radomir's mechanics, everything is fine, except that I wouldn't convert tilde+newline to forced newline; trailing invisible blanks would have an effect very difficult to track down for most authors. GNU make has this problem, which is a real nuisance imo.
Ideally, what's between angle brackets for plugins and placeholders should be better defined (escape, quotes, etc.), but I'm affraid we won't reach easily a consensus. I'm most probably going to have block plugins similar to block preformatted where nothing is interpreted except for the left-aligned end mark, and inline plugins where the first occurence of right angle brackets marks their end (with "block" and "inline" I mean in the Creole text, not in the parser output); i.e. I'll keep my current implementation, adding basic support for placeholder's triple angle brakcets. So the escape character wouldn't have an effect there either.
-- YvesPiguet, 2007-Jun-06
1) (view wiki source to see the correct markup :-) ) Inconsistency for "Nowiki (Preformatted)". The text says "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."
The example says: "Some examples of markup are: ** <i>this</i> ** "
Is it ok for inline nowiki to be formatted like this?
2) Really no definition lists? ;-)
-- MaxVoelkel, 2007-Jun-06
1) Why would it not be ok for inline nowiki to be formatted like that?
2) Definition lists can be added to Creole Additions.
-- ChuckSmith, 2007-Jun-06
2) Done.
-- YvesPiguet, 2007-Jun-06
From my experience it is possible to break creole elements down to a reasonable set of features for processing on a case by case basis. The main feature is the creole line type, the remaining features are open and closed creole elements. If we treat creole elements as either line type elements, open elements, or closed elements it then becomes possible to easily determine when to escape and when not to escape.
Line type elements describe the block and, depending on their actual type, can contain regular text and/or other open or closed creole elements.
Line type elements include: heading, horizontal rule, lists (ordered and unordered), paragraph, placeholder, preformatted, and table.
With line type elements, starting characters are escaped. Escaped line type elements change the line type itself (e.g. ~== changes from heading to paragraph). The contents of the block are escaped on a case by case basis. With preformatted, nothing is escaped. However, there is a special case for one or more escape characters (i.e. tilde) followed by three curly braces on a line by themselves. In such cases, following tradition, one tilde will be dropped to effectively escape and also allow representing any possible text inside the preformatted block. With placeholder, nothing is escaped. Perhaps it should have a special case like preformatted?
Open elements contain regular text and other open or closed creole elements.
Open elements include: bold, italics, and table (cell separators).
With open elements, all regular text is escaped. A tilde followed by a non alpha numeric character which is not a tab or a space (e.g. [^\t 0-9A-Za-z]) will drop the tilde and remove any special meaning from the following character.
Closed elements contain regular text, optional modifiers generally followed by regular text, and the necessary closing characters or end of line or file.
Closed elements include: links (regular and free standing external links), image, nowiki, and placeholder.
With closed elements, nothing is escaped.
When a series of closing characters exceeds the minimum requirement (e.g. ]]]), only the final characters are used to close the element. This technique allows natural nesting of special characters to achieve results which might otherwise require escaping (e.g. [[Home|[{{home.jpg|{Home!}}}]]] produces <a href="Home">[<img src="home.jpg" title="{Home!}" />]</a>). Note: It was necessary to escape the example to produce the desired effect here.
I don't believe pipe is legal in filenames and URLs (please correct me if I'm wrong!) and therefore doesn't present any issue here. Image source and link references are always specified first in their respective creole elements so pipe as an optional modifier works as expected, and does not require escaping.
This escape design provides a simple, safe and effective escaping mechanism which does not force authors to change important filenames and URLs to avoid accidentally escaping them. Of course, this idea depends a lot on the available parsing tools. It is implemented and working well in my Ragel based creole parser.
I must admit that I tend to over complicate things. If there's a better way to escape without forcing authors to change important filenames and URLs then let's do that. If I need to change my thinking around this issue then please help me with it. Actually, now that I've gone and written all this, it looks way too complicated! I'll respond later.
MarkWharton 2007-06-07