Creole 2.0/Discussion - WikiCreole 2.0 Wiki

Contents

HTML5

Is there somewhere a discussion of html5 changes in creole? e.g.: The <tt> tag is obsolete in html5. It was reccomended to use <tt>, see: http://wikicreole.org/wiki/Creole1.0#section-Creole1.0-NowikiPreformatted (site is down). So use <code> instead of <tt> ? -- JensDiemer 2011-08-08 12:46:09

As I see it, WikiCreole is not an abbreviated form of HTML, or anything like that -- there is no direct correspondence between WikiCreole markup and HTML tags. W3C and others are recommending that you write "semantic" HTML as much as possible -- that is, mark the text up with tags that have meanings, and use CSS and other techniques to give it the right presentation. On a wiki site, you rarely have control over CSS, so unless the site admins provide you with specialized rules and macros for expressing the meanings you need when talking about the wiki site's subject, you have to make do with the basic, presentational markup, possibly explaining it in the text of the page if it has some special meaning. But that means that using the "semantic" HTML tags for that presentation is wrong -- because you are putting meanings on markup that didn't have them -- in particular, when formatting preformatted text with <code> tags, you are assuming that it is always going to be used for computer code. But that is not true, and you can't really tell people to only use it for code. Hence, to be correct in the spirit of HTML, you should be using tags that don't really carry any additional meaning besides the presentation.

Now, there is a number of choices available:

You can use the <tt> tag, which will keep on working in all browsers, you will just get warnings from the validators. It is considered "obsolete" because they want you to use the tags that carry additional meaning where possible, but it is really not possible in this particular case.
You can use a <span> tag with a class and accompanying style definitions that will make the presentation right. This seems what the W3C and others recommend currently, but it ironically makes the resulting HTML harder to handle programmatically -- there is no way to tell which spans are for preformatted text and which are for other things.
I suppose it would be nice to agree on the name of that class then, so that you can convert from creole-generated HTML back to WikiCreole without having to guess which spans mean "preformatted". This would require an update in the spec though. I think it's a good task for Creole 2.0.

I'm going to contact the guys who host the spec and let them know about it being down. -- RadomirDopieralski 2011-08-08 19:37:17

URL Discussion

Moved to Creole 1.0/additions/Discussion. It's easier to not repeat ourselves all over.

URLs after Link explanation text

The the old wiki has a quite nice graphic that shows that many wiki engines choose to use the much more user friendly way of putting the explanation first in a link. This is different from html - but it should not be the goal of the wiki engine to read like html. Especially if many links are long and used in text or in a list it is really hard to find where the description is (it is usually pretty short compared to the link). Also this mirrors the very old and often used free form that people use when just writing ascii text about something: First the explanation and then the link. Often in the form of (Find more info here: <url>)

Therefore I propose that for Creole 2.0 explanation before links should be made standard. --Martin Häcker

I agree with Martin Häcker, and for a reason not yet cited here (although I did put it forth somewhere a long time ago)--I often want to sort a (for example, bulleted) list of links--the sort is always (for me) based on the text (explanation), not the URL (link). If it is arranged as Martin proposes, it is very easy to sort in almost any editor. --Randy Kramer, 20110105

We had a long and winding discussion about this on the old wiki, and we failed to provide any hard facts and evidence in favor of either approach. While the order you suggest might be favored when you link to urls, it might not work as well when linking to other pages on the same wiki (and a wiki usually mostly has internal links). In the end it turns out to be a matter of preference and habituation. I really don't see any compelling reasons to change the initial decision (even if it wasn't based on hard evidence) and break compatibility not only with half of the wiki engines that made similar decision, but also with earlier versions of Creole itself. Remember, that the main goal of creating this project in the first place was to find a cure to the interoperability nightmares caused by proliferation of different wiki markups. Introducing more variety in behavior would be counter-productive. -- RadomirDopieralski 2009-03-13 17:38:24

Making Creole 1.0 additions mandatory

I think one of the first things one should ask is whether there are Creole 1.0 additions that should be made mandatory in the next version. I think ^^superscripted^^ and __underlined__ might be candidates. What do you think?

Since nobody replied, I'll give it another try: Creole 2.0/1.0 additions in 2.0. -- MarioLenz

Markdown uses double underscores for alternative bold. -- JAbits

Simplicity vs. power

There have been some proposals on Creole 1.0/additions/Discussion about CSS or something similar... I strongly advise not to bloat the standard. Feature creep is probably the biggest problem in IT, both in software and in standards. Adding more and more features to please everyone inevitably leads to frustration. WikiCreole should stay lean and mean in order to make it easy to implement and use. "Keep it small and simple" is a very wise design goal on the long run. For example: CSS might be replaced by something else one day, but it is quite likely that people will always use bold and italics, headings, tables and lists.

comment of FBnil: In WikiOnAStick we use css to complement the markup. For example, a strike-through produces a strike tag with class="woas_strike". This class can then be updated by the user to make it red, or cross it out with XXXX instead of a line. So there is a strong interaccion with CSS. Now, the only way your page is going to look as you want it is to use HTML with inline styles, true, but we can wrap that into a macro, and then it looks like an extension... in conclusion: keep the core small, the rest is possible using <<macro's/extensions>>

More powerful image tags

Here we can add a space on one or either side of the imagename to center it, or float it left/right The questionmark ends the imagename and starts the optional markup, width and height, and a way to set vertical alignment (very useful for small inline images). Example: {{http://www.gnu.org/graphics/heckert_gnu.small.png?16x16:bottom|a gnu image}} The third option is what we use in our wiki, but it might be bloat for Creole 2.0. It gives the image a class, or if a colon is detected, it adds it as style.

exclamation is a one-liner note

I know this conflicts with headers (for which we use = but many Wiki's use !), but I'd like to propose:

! {{images/info.png}} This is a colored information div with an inline image and important information

This is an extension to this syntax (but might be feature bloat):

!{bluebox oval} This is a div with class="bluebox oval" and presents the information in a different way

Documentation

Nesting

The documentation of which markup element can contain which other kinds of elements is a bit unclear in Creole 1.0. It would be helpful to state clear which element types can be contained.

Example:

Paragraph
Can contain: Break, Image, Link, Strong Text ...
Can be contained in: none

Strong Text
Can contain: Emphasized Text, Link
Can be contained in: Paragraph, List Item, ...

Removing "Alternate Link Syntax" from additions

According to WikiMatrix, only PmWiki supports this (see WikiMatrix' external and internal link markup). Since WikiCreole is also about interoperability, I would remove this addition in Creole 2.0. It's like this: Whoever uses this syntax- be it a wiki engine developer or a user- is not concerned about interoperability, otherwise they would use the WikiCreole standard that is guaranteed to work in all WikiCreole wikis. If you're concerned about interoperability, stick to the core standard. If not, why stick to the additions instead of doing it in a completly different way?

Besides, as someone stated on Creole 1.0/additions/Discussion: "There should be one, and preferably only one, obvious way to do it."

Italics in headings

This observer would like to comment that it seems odd that italics can't be used in headings. I can't find an explanation for this decision and this would be a good fix for 2.0. It's quite reasonable to want to use italics for emphasis or foreign terms used in headings. Ironically, the immediate previous section heading in this page could benefit from this change.

List items with newlines and paragraphs

What do others think of this markup proposal?

Example list caption:
  * Item A (conventional)
  * Item B (continued), ending with newline.
    : Item B continuation in the same paragraph.
    :
    : Item B continuation in another paragraph.
  * Item C (conventional)
  Preformatted text, such as this, without any prefix terminates the list.
Regular text, such as this, without any prefix also terminates the list.

comment of FBnil: Looks logical, and looks like indentation (but because there is a space before the :, it should not conflict. Personally I use backspace to continue a line. Another option is to have them at the same level of the asterisk.

Hierarchical Document Trees and Navigation

I would like to see a conversation around standardizing a way to establish parent-child relationships between pages (or between multiple sections within a single body of wiki markup) for the purposes of hierarchical document representation and navigation.

Before the internet most information was in books. Many books were organized into chapters and sub-sections that directed the reader through a logical progression of the material. Flip to the table of contents in the front and what you will usually find is a hierarchical tree-like organization of information. Flip to the index at the back and what you have is essentially a keyword search engine.

Today most wikis have the keyword search engine (the book index), but many are weak when it comes to defining a document hierarchy (the table of contents). Now not every wiki has content that lends itself well to a document hierarchy, but it is a common enough use case that many "Table of Contents" implementations and "Tree Navigation" extensions have sprung up for the various wiki engines. The syntax for these varies widely today. A standardized way to represent a document hierarchy would be a good thing for wiki markup.

Furthermore, many book oriented document systems have been developed that embrace this type of tree organization, running the gambit from TexInfo to DocBook. But many find such systems awkward or impractical to use. Recently some book style document generators have been embracing wiki markup as a way to represent content. Document generators such as txt2tags and AsciiDoc are examples of this. Even DokuWiki is partially into this space. Systems such as these could also greatly benefit from a defined standard for hierarchy representation in the wiki markup.

It would not take much to enable this. Much of the functionality can already be done explicitly today with just urls, but a few tweaks could help. One idea is extending the url syntax as follows:

[[link_address|>|link text]] : Defines a link to the Next page
[[link_address|<|link text]] : Defines a link to the Previous page
[[link_address|^|link text]] : Defines a link to go Up one level to the Parent

With simple additions like these a wiki engine could deduce and display navigation for hierarchical documents on it's own. Also document generators (and wiki engines for that matter) could automatically build tables of contents from these links by combining data from multiple pages.

As an aside, for document generators it's common to have multiple sections/nodes/pages in a single body of markup. For those cases it would be useful to have an indicator that marks the beginning of a new section/node/page within the markup. That indicator would contain the link address to be generated, or in the case of a wiki engine, a url or anchor that can be referenced from elsewhere in the wiki:

[[link_address||link text]] : Defines the beginning of a new node within a single body of markup containing multiple nodes.
(Or maybe this can just be some variation of anchor syntax?)

Granted those forms of syntax are just quick ideas without much thought behind them. My real point is to start up a discussion in the community of how document hierarchy might be standardized, paving the way for new features such as navigation and automatic contents generation in wiki engines, as well as helping Creole make inroads to wiki markup based document generation systems.

Aims and Compatibility

Hi, I've added an aims and suggested compatibility onto the front page. I've done this not only because I think it is necessary if creole is going to go anywhere that it understands what it is trying to achieve but also because I think it will provoke people to think through some of the issues (like e.g. subscript). The big problems Creole has had is that the application developers are reluctant to include things in the standard which they personally don't see a need for. This is entirely the wrong way around, because far from only agreeing the "worst common denominator spec", what users are crying out for is the other way around: "common markup for common formatting, and the surety of knowing that you won't get caught by some application specific oddity in the way they implement their markup". So, it isn't enough to agree on how to do a link, but then find that single square brackets have some meaning in a particular wiki, so that you have to spend hours trhying to understand how that particular wiki might just allow you to enter single square brackets. And what does it matter if Creole specifies a way to do things which many wikis might not wish to do??? COME ON!!! Let's be honest, if you don't want to have references, footnotes, colours or whatever, why don't you just let those who do want those additional features work out a way to do them and allow those who don't to derogate from the specification. So long as the user is told explicitly that the wiki doesn't do some features, then there are good reasons not to implement every feature on every wiki, but there are no good reasons to stop people who do aspire to have such features coming to a common agreement.

<What's the point of a specification that doesn't even let me know how this wiki lets me sign my comments about that specification>

If you read the goal statement of WikiCreole you will surely discover, that it was never to force the presence or absence of a certain set of features onto wiki engines. On the contrary, an effort has been made to only define the most essential markup that can be found in most wiki engines, and to leave the standard open-ended. This wiki is open for general public (in fact, I don't think there are any people left who would be willing to take responsibility for WikiCreole), so it may seem like it's simply a wish-list, a place where people can demand features they miss, because when they become standard everybody will be forced to implement them. Personally I don't think it works that way. Even demanding documentation in the standard -- although surely done with a noble goal -- isn't likely to have much effect. Developers won't listen to you if all you do is making demands. What they (we) want is ready solutions for the design problems -- solutions that are maybe not perfect, but at least good enough and agreed upon. And of course, if it comes with free documentation and tutorials that you can reuse -- it's even better.

I don't mean to discourage you from working on WikiCreole -- I can see you are already putting a lot of energy into it. I just don't think there is anybody here to try to convince to your points.

Oh, and by the way, you sign your comments the same way you do it in the real (non-Internet) world, and in many places on the Internet too -- with your name. You might be able to find some of the documentation that you crave by typing 'help' in the search box too. I hope that helps. -- Radomir Dopieralski

CreoleWiki: Creole 2.0/Discussion (last edited 2011-12-14 12:57:14 by RadomirDopieralski)