Contents

  1. Table headings
  2. Colors
  3. Indented Paragraphs
  4. Additional attributes
  5. Anchors
  6. Matching anchors to target IDs
  7. Indented Paragraphs
    1. Use '>' and not ':'
    2. Allow leading spaces
  8. Line Comments
  9. Numbered Headings

Table headings

I would like to add a new proposal about table headings.

For example, take a very simple table, like this one:

head 1 head 2
cell 1 cell 2

It was created using the following Creole 1.0-compliant code:

|=head 1 |=head 2
| cell 1 | cell 2

But it could be simpler and quicker to use exclamation marks:

! head 1 ! head 2
| cell 1 | cell 2

What do you think about it? -- AmauryBouchard

I can see at least two big problems with it:

I can also see a number of smaller problems that somehow make this solution look bad in my eyes:

Of course, wiki engines that use Creole are free to extend it with its own markup, if their authors think it's necessary, but I really think this particular proposition is not thought out throughfully. -- RadomirDopieralski 2008-12-23 21:56:42

Colors

For example :

<span style="background-color: yellow">Go back to work</span>
<font color="red">Call mom</font>
[|yellow|Go back to work|]  => black font on yellow background
<|red|Call mom|>            => red font
<\LABEL:FOREGROUND_COLOR;BACKGROUND_COLOR/>
<\important:red/>         => a colon is followed by a foreground color
<\urgent;yellow/>         => a semi-colon is followed by a background color
<\todo:#c4acd8;orange/>

{{urgent{Go back to work}}}
{{important{Call mom}}}
{{current{Think about Creole Wiki}}}
--{{current{Yeah, but now it's done}}}--
<\LABEL:FGCOLOR;BGCOLOR!BOLD!STRIKE!UNDERLINE!ITALIC/>
<\important:red!bold/>
<\urgent;yellow!underline/>
<\done:grey!strike/>

{{urgent{Go back to work}}}
{{important{Call mom}}}
{{done{Yeah, but now it's done}}}

But... it begins to go far away of the "keep it simple" principle... -- AmauryBouchard 2008-12-23

Sorry for being so negative, but again I have some problems with this proposal:

I spent some time on the Creole 1.0 wiki, and I didn't find any discussion about text color. Maybe I missed it.

I don't agree with your arguments. I'm working on "wiki syntax-enabled personal notebooks and to-do lists" rather than usual wikis, and it brings special constraints.

But, you get a point with CSS.

-- AmauryBouchard 2008-12-24 09:32:00

Agreed about difference between emphasis (italic, different font like sans-serif/serif or monospace), and highlight (bold, color, different font size, letterspacing, background, underline). In "standard" wiki markup, as well as in books and similar texts, the number of different highlighting techniques is usually very limited -- because they are distracting, and because the readers will often want to add their own highlighting. You usually have some bold text, different sizes of headings, sometimes indentation or spacing. Books made specially for students will often have more highlights, like "notes", "warnings", "examples" and such -- but they are usually whole blocks of text, not just single words or phrases. So we have two kinds of highlights: inline and block.

Another observation is that you usually don't care about how the inline highlight really looks like, as long as it's consistent. You also want it to be short and convenient. I think that using markup like %%highlight%%, &&highlight&&, ::highlight::, @@highlight@@ and of course __highlight__ could be good choice. How they look exactly is irrelevant, as long as they are different and sticking out of the text.

Allowing decisions about exact looks of the elements in a multi-user environment like wiki is bound to cause inconsistencies and even conflicts, not to mention impairing accessibility and portability. For example, letting users choose the colors will hurt in environments where different users can use different themes with different background color.

The block highlights are easier -- their presentation may be defined in the theme, and they don't have to be as concise and easy to use -- so you can use regular macros or some variation of the preformatted block markup.

This is an example of a solution that seems nice to me. It still has a number of problems, of course, otherwise I would propose it already. -- RadomirDopieralski 2008-12-24 10:22:21 -- RadomirDopieralski 2008-12-24 10:22:21

Sorry Radomir, but I don't really understand what your solution is (beyond the "stay as we are" point). Yes, in a multi-user environment we must have consistency: the same meaning must be rendered the same way. But how can we define the different highlights needed by users?

A notebook or a todo-list has really constraints. Typically, it's based on bullet-point entries. And most of users care about how they can highlight these entries, because they will see a bold entry differently than a yellow-highlighted one or than a striked-out one. And from my point of view, each of them are inline hightlights.

So, I'm back to the question: How can we add highlights (with different "severity" levels) to text, staying in a wiki-style syntax? I think there is 2 ways to answer it:

With the last proposition (using exclamation marks), the Creole syntax may only define the "concept", and let each wiki implementation deal with the style details.

-- AmauryBouchard

This is how the original wiki (and later many clones) did it with "'". It resulted in a number of troubles.

Exclamation point is not used for titles precisely because it's not suitable to be used for markup -- it's too common in everyday text, both as a single character and in groups, also together with other punctuation. Consider "It's alive!!!", "!Que pasa!" (straight exclamation mark is often used in place of "¡" when the latter is not available).

It would be possible to use some less common character, and that's what I had in mind.

Repeating the markup character to indicate severity is troublesome if you allow nesting -- the text becomes impossible to parse without unbound lookahead, and some expressions become inherently ambiguous. -- RadomirDopieralski 2008-12-24 12:57:50

I understand your argument. Well, I'm not stuck on the exclamation mark character (but it has the advantage to express some kind of emphasis). All that I want is to find the best possible syntax to manage criticity levels of highlighting, and try to get a consensus about it from the people involved in Creole. So, we can think about it together: what syntax can be safely used?

Any other idea?

Damn, ^^ is already a Creole 1.0 addition for superscript...

-- AmauryBouchard 2008-12-24 17:19:00

I believe a general approach is needed for adding xhtml attributes (css flexibility is needed by EVERYONE) to 1.0 syntax, both block & inline elements. For instance

=== A level-3 heading === +class=important-heading +style=color:black;background-color:white;

A separate tag of course is needed to define the *important-heading* css class.

-- John (2008-12-30)

Perhaps I can suggest a possible way to include CSS styling (and I second the former writer in the need of it) that would fit rather naturally. I think the most needed way of CSS styling is adding CSS class names to an element. This way, the "basic" Creole elements could be extended if need be. My proposal is to mirror CSS syntax, i.e.:

.important This is an important paragraph!

#myId This is a paragraph marked with an ID

=#anotherID This is a first-level heading with fragment ID

And **.myClass this is bold with myClass** to show inline use.

This would be a short way to express CSS styling (and providing fragment identifiers that could be used as targets). I've used a similar syntax for quite a while now, and it comes in very handy. It could be a way to systematically extend the Creole syntax. Two additional elements I would suggest are generic SPAN and DIV support so that special cases can be handled (i.e. "figure" with image and associated caption). Using the extension syntax to provide this looks a little bit awkward to me (I think it should be used for less generic needs).

I don't think that it is always necessary to have user-definable CSS styles (but perhaps this would be a good use for the extension syntax). I'm thinking more in the way of specific CSS styles provided by the maintainer of the Wiki.

-- ChristianAugustin (2009-02-22)

Hi Christian,

Starting a paragraph with a number sign (#) wouldn't be doable as that is already used for lists. The other ideas are very good though. I had a very similar suggestion (with a bit more typing):

{.important} This is an important paragraph!

{#myId} This is a paragraph marked with an ID

={#anotherID}This is a first-level heading with fragment ID

And **{.myClass}this is bold with myClass** to show inline use.

-- StephenDay (2009-02-22)

Hi Stephen,

yes, I guessed that problem afterwards. With the system I used, there was a space needed after the number sign to get a numbered list (which is not recommended by Creole, as far as I remember). But what with bold (starting with a star) or monospace (proposed to use number signs)? Okay, it depends on the order of parser expressions and some context, maybe it simply works because it is a symmetric pattern etc., but it should have similar problems (think of nested lists, starting with two stars, followed by some bold text - how can the parser guess which stars should be paired ...).

Typing curly braces is tedious when touch typing on German keyboards (a little bit better on Mac, but very ugly on PC), but your suggestion looks quite reasonable. Another way could be to have another "special" character in front so that it is easier to type and does not need a closing character.

On the other hand, your suggestion opens some other possibilities, perhaps to include CSS:

{#myID $color: red; background: yellow;$ "This could be the title attribute" !de:DE}
This would be a paragraph with ID "myID", red font and yellow background,
a title attribute and a language attribute of "de:DE" ...

Especially setting languages on paragraphs (or SPANs when using foreign words or phrases) is something to consider for a Wiki. Parsing is rather simple with your suggestion (BTW, the system I used had a similar syntax, using [...], and it was tedious in the long run; my suggestion was made to streamline typing and get rid of those hard to type characters).

Thanks for your suggestion (and I'm looking forward to Radomir's opinion ... ;-)

-- ChristianAugustin (2009-02-23)

After thinking about the # problem, there could be a rather simple solution by preceding an "attribute run" with a &:

&.important This is an important paragraph!

&#myId This is a paragraph marked with an ID

=&#anotherID This is a first-level heading with fragment ID

And **&.myClass this is bold with myClass** to show inline use.

Not very nice looking, but easy and fast to type. Another way could be to start always with a dot (like .cssClass for CSS classes and .#myID for IDs).

-- ChristianAugustin (2009-03-02)

Indented Paragraphs

Oddmuse produces the following when using the Creole Additions extension:

<p>This is a normal paragraph.</p>
<p style="margin-left:2em">This is an indented paragraph in two lines.</p>
<p style="margin-left:4em">This is more indented.</p>

Is there any drawback that you can see?

The reason Usemod, Mediawiki, and Oddmuse with the Usemod markup extension use dl/dd to indent text is that this will also work on text browsers. It works without CSS, which is always a boon.

-- Alex Schröder

That reminds me of the fact that there is no "real" blockquote markup in Creole (indenting paragraphs is not the same in my opinion). But I have no idea how this could be done (other than using the extension/addition syntax). Ideas anyone?

Apart from this I would find the "original" approach (using DIVs to encapsulate the indented paragraphs) a little bit cleaner than using hardcoded styles for the paragraphs themself (there is a possibility of grouping consecutive paragraphs inside of one DIV). I wouldn't like the idea of "abusing" definition lists to indent text (even though they also work with text-only browsers -- but blockquote would do too). I know, it's all about "appearance" vs. "intention" ...

-- ChristianAugustin (2009-02-27)

(Hmm, discussing with myself ... ;-)

There was a proposal in Creole 1.0 for blockquotes:

"""
This is blockquoted content, including all the "usual suspects", like
* unordered lists
## numbered lists
etc.
"""

Normally, blockquotes are indented by default and can be styled via CSS as the wiki maintainer likes it. It should work with text-only browsers and screen readers. And it would enable proper quoting of content. (And there was a proposal for inline quoting with ""..."" -- looks good to me).

-- ChristianAugustin (2009-03-01)

Additional attributes

MoinMoin's default "moin wiki" parser (not the creole wiki parser we also have) supports creole-like linking and transclusion. The link syntax was changed from moin 1.5 to 1.6 to get rid of the rather complex/broken old syntax and the respective complex/broken code in the parser.

I like the easy link syntax of creole much and even more to just have 2 fundamental things solved by some sane syntax:

Consistent usage of those 2 patterns makes stuff much easier, better predictable and requires less magic.

But we had to extend that syntax a bit - just [[ target | label ]] is just not powerful enough.

We use now an (optional) 3rd field, like:

The params field can have stuff like:

See http://master.moinmo.in/HelpOnLinking for details (this stuff was implemented in moin 1.6/1.7).

-- ThomasWaldmann 2009-03-02 12:07:47

Anchors

Another thing I recently found needing improvement is specification of anchors:

Currently moin 1.8.x just uses `TargetPageName#anchor` syntax.

If one allows # as a valid character in pagenames, this is of course a bit ambiguous and needs some hacks in some cases:

Better would be this:

[[ target_without_anchor | label | #anchor ]]

With that, the parser knows that there is never an anchor spec contained in the target, thus no ambiguity, no hacks needed. If someone wants to link to an anchor, it is given in the 3rd field.

Note that according to the URL RFC the anchor ("fragment id") has to be at the very end of an URL (so, if the URL has a query string, the anchor is AFTER the query string). Thus, having it a) separate from pagename and b) in the field where the qs stuff is also, is not that far fetched.

-- ThomasWaldmann 2009-03-02 12:07:47

Matching anchors to target IDs

Sometimes you want to create target IDs from stuff like headlines (and not give them some weird and arbitrary generated ID).

Problem: in headings, about everything from unicode is allowed, HTML IDs / fragment IDs just allow a small subset of this.

Thus, for generating IDs from some arbitrary text you need some id_encode(text) transformation.

If text contains only characters that are valid in IDs, that id_encode transformation should be an identity transformation (thus will output same text).

If text contains other characters, id_encode has to map them somehow to the valid chars:

With that, we can create a valid and sometimes even well readable ID from some arbitrary text (like some headline text).

BUT: assuming that there was some non-valid char in the original text (before in went through that id_encode transform), then the output used for the real ID will be different.

A wiki page author should not have to bother with this (most people are bad at utf-7 and urlencoding etc. :) ).

Thus, for the anchor links, we should use the same transformation, so they can simply give the same text there and the resulting anchor (fragment ID) in the URL will automatically match the generated ID at the target.

Example:

[[|jump to down there|#down there]]
...
...
...
...
== down there
...
...

Notes:

-- ThomasWaldmann 2009-03-02 12:16:40

Indented Paragraphs

Use '>' and not ':'

I don't see why both should be supported. Especially as the colon is proposed for use in definition lists.

Allow leading spaces

Remove the requirement that the character (':' or '>') be the first on a line. This breaks with the Creole "convention" that leading spaces are OK.

-- StephenDay 31-March-2009

Line Comments

It is often useful to include comments (that you don't what to render) in raw wiki text.

I propose a mark-up for commenting on a line-by-line basis. This would not allow a line to mix rendered content and comments, thus making implementation easier. The choice of mark-up to use is up for debate. Here are some ideas:

<!-- Hard to remember and type. Implies a closing "-->"

/* Better, but implies a closing "*/"

# (or ##) Conflicts with existing mark-up

Any other unused mark-up...

Comments inside pre blocks must be rendered.

-- StephenDay 4-April-2009

Basic used "'", but I suppose that's too common, even at the beginning of sentences. Windows .ini files and some other config files (dns zone files) use ";" for comments -- I think that this is rare enough. The question is, why do you need invisible comments? Isn't a wiki page an eternal work in progress? Why would you want to hide parts of it? Shouldn't everyone be invited to the unfinished text, not just the ones who click on edit?

I used % as a line comment sign with my parser. This is stolen from PostScript/PDF ;-)

-- ChristianAugustin, 2009-08-03

Numbered Headings

Are there any plans to introduce Numbered Headings, similar to how MS Word uses "Outline Numbered" sections.

Something like this:

1. Heading 1
Some text.
1.1 Heading 2
Some more text.
1.1.1 Heading 3
Even more text.
1.1.2 Heading 3
Even more text.
1.2 Heading 2
Even more text.
1.3 Heading 2
Even more text.
2. Heading 1
Even more text.

It would be similar to a numbered list for the headings, except that it includes all the numbers of the higher level headings.

Any comments? DanSmart - 23-Apr-2009

I don't think this is a good idea. Whether headings are numbered like this or not should be handled by the wiki engine, just like size or other styling. -- MarioLenz 2009-04-23 17:29:26

Automatic numbering introduces a number of problems: Should there be a way to skip a number and jump to the next one without a heading? A way to have an additional heading with the same number? How would you refer to the headings if they can be renumbered at any moment? If you still have to refer to them by text, what good are the numbers? What about wikis in different languages/scripts, what digits/numbering should they use? How should the numbers be formatted in right-to-left languages? What if you want to start numbering from the level two headings, or make level one headings start with a digit in front already (for example, when the page is just one of many chapters)? Not including this flexibility will make many users unhappy. Including it will turn Creole from a basic wiki markup standard into some kind of a professional, full-blown content preparation system that is hard to implement and learn. I think it's best to allow the authors/admins of particular wikis decide on how to handle numbering of headings, even if we risk that some of the content might suffer when moved between wikis. -- RadomirDopieralski 2009-04-23 18:33:04

CreoleWiki: Creole 1.0/additions/Discussion (last edited 2009-08-03 23:52:27 by RadomirDopieralski)