First of all, I'm fairly new to wikis in general, and I probably have yet to fully grok the idea. Nonetheless, I've become quite taken with it, and I've started my own to facilitate a research project of sorts (using ZWiki). To explain my problems with Wiki markup, I need to explain the use to which I am attempting to put it. The project is this: I'm writing an FAQ for an email list catering to a particular subculture. I needed a way to collect and organize hundreds of quotations extracted from the past archives. I wanted something that would let me grow the organization gradually, rather than having to define the organization before I could start collecting data. I also wanted to be able to let others add to, update, and refactor the data with a minimum of technical knowledge and/or setup. I.E., I wanted to be able to tell people "If you want to help me, just go to http://blahblah and you can edit the pages yourself... you don't even need to know HTML". A wiki seems to be the perfect system for this kind of collaborative research.
Here's the problem. For the task at hand, choice of formatting rules is not just arbitrary or academic. The vast majority of the text I'm working with has already been written, without a wiki in mind. Thus, the most desirable WikiSyntax would be one that understands the way people write plain text for each other, and adds markup appropriately. Ostensibly, this is the goal of most or all wiki formatting rules: readability in source-form, as well as processed form. However, every wiki I've looked at has had a combination of sensible formats and inexplicable, non-intuitive formats that no one would naturally (to my mind) type. Every single engine I've looked at has had at least one bizarre formatting rule that would require either significant reformatting of existing text, or education of the editors.
So, here is my list of the less-than intuitive formatting rules that I've found implemented in various engines; and their more intuitive alternatives. While these were influenced by the task of converting a mailing list archive to wiki-format, I think most of these are applicable to any type of wiki. My idea is that it is not difficult to implement a text pre-processor that recognizes the common idioms of human-to-human text; and that there is no reason to invent new, counter-intuitive formatting idioms when common idioms already exist. I'll probably write a perl script to prove this point, as I have the time.
Silly Rule: Requiring a single underscore at the start of a line; or requiring an HTML HR tag.
When people write horizontal rules, they put a row of dashes on a line by themselves. Fortunately, most engines handle this construction fine.
Silly Rule: List items must be separated by blank lines.
I don't know if this is peculiar to ZWiki only; but it is unnecessary and unnatural.
Silly Rule: Requiring the use of a single character.
Silly Rule: Requiring an exact number of spaces before and after the bullet character.
People use '-', '*', 'o', and probably others, for bulleting lists. All of these should be supported; and as long as:
The text should be interpreted as an unordered list.
Silly Rule: Requiring the use of the '#' character
When people write numbered lists for other people to read, they use actual numbers or letters, followed by either a period or sometimes a close-parenthesis. It shouldn't be too difficult to recognize this pattern and renumber if necessary. Those writing primarily for wiki-consumption should be able to use the '#' idiom if they like; or simply use a repeated '1' or 'a' at the beginning of each list item and let the preprocessor auto-number the list. WikiWiki does this for numbers at least. Supporting actual numbered lists makes reformatting old material much less of a burden.
Silly Rules: Many, and varied. None of them look natural. Definition lists look like this:
Term: Definition of the term.
And they should not need to be written any differently for a wiki to recognize them. I know at least one wiki supports this.
Silly Rule: Requiring the use of the BLOCKQUOTE tag; interpreting '>' prefixes as something other than a quote.
Various approaches have been taken to quotes, and I'm not sure which is the best. However, I DO know that prefixing lines with '>' has become a ubiquitous idiom for quoting; and text quoted in this fashion should be treated as blockquotes. This would certainly make reformatting emails for wiki content much easier. Rules based on indentation of text blocks might also be a good idea.
Critique moved to EmphasisPattern
Bravo! I agree with most of your points. And I'm willing to help the author of the UseMod wiki engine to fix all of this, should he be willing to do it. The only thing I don't agree with in your list is the use of *bold* /italic/ and _underline_ conventions. [see EmphasisPattern] -- AlexSchroeder
Some of these suggested rules actually make it harder to then edit the text later, especially the quoting. I don't know anyone that types the >quotes by hand. Perhaps a text-processor to convert some of these rules to wikiform? For the record, I like UseMod, don't like WikiWiki, mainly because of the spacing/tab rules. Unfortunately I think we're stuck with some of these rules, due to the necessity of having multiple rules and avoiding confusion. That is, what you might want as insignificant in one place, is used to signify a different rule (eg. leading space: ignore for bullets, or indicate preformatted text?) -- EricScheid
I agree, some make it harder to edit later. But the > quotes are there to paste and copy email, not to quote text you might want to process further. I don't mind the leading colon `:' rule for those texts. But it would have been OK as well if we had a leading `>' rule for those paragraphs. When one paragraph is one line, one `>' is enough. When a paragraph is multiple lines, a `>' at the beginning of each line is enough (such as pasted email). I think code can deal with the problem of one leading `>' on the first line of a multiple line paragraph.
As to leading space: I prefer it if that disables most additional markup rules -- no bullets, no horizontal lines, etc. Usually the leading space is used for source code anyway, so who wants HTML bullets in source code anyway?
We can keep old rules for backwards compatibility, but I think we should strive for more reasonable alternatives where the current rule is silly. The apostrophe rules are the worst in this respect, even more so since they cannot be easily mixed on one line, eventhough UseMod requires many paragraphs to consist of one line (eg. list items). -- AlexSchroeder
I just stumbled on this page when someone on the PhpWiki mailing list pointed it out to me -- it seems painfully obvious now, but avoiding silly markup is something I've worked very hard on on the NBTSWikiWiki? (http://www.nbtsc.org/wiki), since it's a constantly shifting userbase, and I'm the one who always end up explaining things that are non-intuitive. I'd like to think I've done relatively well -- though there's no support at all for numbered lists so far. My latest rewrite has added blockquotes for email pasting, and the wiki recognizes MIME headers as such, and formats them in an email-like form, making a cut-and-paste of an email (from my mailer, MH at least) work almost 100% of the time.
In defense . . .
While it's true that WikiSyntax should strive to meet plaintext conventions, there are limits to this. For instance, the "more intuitive" TableSyntax I presented is not easier to use than the MoinMoin syntax + UseModWiki backslash. I also don't think having a million ways to specify a bullet list is less complex than using only one character. After all, many people learn WikiSyntax from the edit box.
Addressing other concerns, I don't think
<BLOCKQUOTE/>ing has any purpose on a wiki that isn't already served through other means such as indentation and italics (the proper ways, typographically speaking). As others have pointed out, there has been no better emphasis syntax invented than the EmphasisPattern. One of the goals of WikiSyntax is not to accidentally interfere with normal text. This is why on UseModWiki ordered lists don't actually use numbers. It's not entirely clear from context whether the user wants a numbered list or is just starting a paragraph with a number. e.g. 42 swallows flew coconuts to England this year. should not be interpreted as an ordered list. As WikiWiki spells whitespace (cf Wiki:SpellWhiteSpace), it can discern a numbered list from a number as a "word".
ZwikiClone is unique, I think, in allowing the page author to choose the syntax rules used to transform the page for presentation. You could do something similar by having a "textfile filter" that attempts to cook any textfile down to some sane representation in WikiSyntax. This is never perfect, however, but it shouldn't be too difficult.
<center> nope </center>