Features / Usability

Features / Usability

Wiki Syntax

posts: 289 United States

I've selected TikiWiki to try to convince my boss and co-workers to stop using network file shares for endless, unsearchable documentation that gets lost among a mass of junk. Tiki appealed to me for many reasons and the more I use it, the more features I discover and the more I love it. However there is one thing that bothers me slightly and that is the markup itself. There seems to be a lot of inconsistencies and I don't find the markup particularly intuitive at times.

As a long time user of TiddlyWiki, I found the syntax of that wiki to be more intuitive. As an example it seems logical to me to use underscores to denote underlining because of the visual similarity (which TiddlyWiki does). Likewise Tiddly uses double forward slashes to enclose text to be rendered in italics (as in "//italic text//"), which again gives a good visual representation of what the markup does, which in turn makes it easier to remember. I appreciate that I can use "quicktags" but to be honest, when you're hammering away typing out a new wiki entry, it's actually not very quick to have to stop, highlight particular text and click on the quick tag. I think a lot of the time it's just as fast to type it as you go, without the need to go back over the text inserting all the necessary markup.

To speak of some of the inconsistencies; It's strange to me that some markup requires {TAG(tag=)}, while some other markup has it's own curly brace name like {SUB}. In the example I gave why is there no "{SUP}", furthermore the "tag=" seems redundant (although there may be other attributes that I don't know about so I can understand the need for this if that is true). In both these cases, these seem like reasonably common text formatting options that I would have though would have some kind of "regular" markup like bold, underline and italic. For example "^+superscript text+^" for superscript and "^-subscript-^" for subscript (see further down for avoiding conflict with box markup when using "^"). Likewise why does strike-through use the "{TAG}"s, when you could do something like "strike-through text" instead. I realize this is somewhat to do with which code portion renders the markup but I feel that THE most common text decorations/formatting should be part of the base markup.

To further confuse matters you then have different types of tags that use the tilde "~", for non-processing and colored text. There seems no rhyme or reason for lumping these two together, although granted the syntax is slightly different in each case. Along those lines it would be nice, if you didn't specify a color that text could be highlighted so "~~highlighted text~~", would be text that has its background color changed. In addition to this, most markup syntax doesn't work over multiple lines (which is fine) but then you have something like the box ("^") that does. Wouldn't it be more consistent to reserve the hat symbol for other markup and use "~box~ some text to be in a box ~/box~" instead? That way at least all the tags that use tilde with a corresponding closing tag could be viewed as tags that work over multiple lines.

Another inconsistency with markup is when used in tables. Some of the markup seems to get processed and so of it doesn't. Is this a feature, a bug, a configuration problem or pure random chance? For example I can use "::-=Text=-::" to make a centered "title bar" table heading (a feature that seems to be missing for tables i.e. No way to differentiate table heading from table content) and that markup will get processed. However text that is bold or monospaced will not. Am I doing something wrong here or is this by design?

I could go on but I know this is not something that can be addressed without breaking everything and starting again (something that I am NOT suggesting!). I realize this thread sounds a bit like a rant and in a way it is; I'm frustrated a little bit because I really like Tiki but it seems like the markup syntax is a bit haphazard. Having said that I find overall TikiWiki is really great and I think it could potentially be a very useful tool for organizing and sharing documentation and increasing collaboration. I also appreciate that you can't just go changing the syntax on everybody, so I don't expect anything to come of this thread, I just wanted to share my experiences as a fairly new user.

Keep up the good work.

posts: 4642 Japan

I don't really know how TikiWiki's markup was decided on, but probably the syntax was done as the original coders thought of it, and over time more was added, the TAG plugin added to cover more cases, and so on. This project has a much looser organization than many, and things tend to be added without a lot of top-down planning. So the accumulated result really is a mixed collection, and people are aware of this. There's been talk about moving to wiki creole eventually (http://www.wikicreole.org/wiki/TikiWikiCMSGroupware), but as you say, it's hard to make big changes in midstream, so this will probably be a goal for a major revision in the future.

-- Gary

posts: 289 United States

I appreciate the reply even if it didn't herald any major surprises. I absolutely 100% understand the challenges of collaborative development and how it can lead to complex code. I only hope that the Tiki Devs periodically do a refactoring release where they clean up and optimize the code base, if nothing else for their own sakes so that future development remains flexible and relatively easy. To that end it seems like 1.10 might be a milestone release which will give the devs some time to step back and re-evaluate some of the code.

So "creole" is a proposed wiki "standard"? I've seen lots of arguments for and against standardizing wiki markup. To me it seems like a logical step in which everyone is a winner (eventually), but I can't see it happening any time soon.

I see that single square brackets was mentioned, one annoyance that I forgot to mention in my original post; yes, it is way too easy to accidentally link to bogus targets.

Anyway... enough ranting. I'm still loving Tiki and not looking to go anywhere else any time soon.