wiki-formats

(Difference between revisions)

Jump to: navigation, search
m (Reverted edit of ShizoDic, changed back to last version by AdamBackstrom)
(MARKDOWN)
Line 116: Line 116:
* http://tikiwiki.org/RFCWiki An RFC Draft for wiki syntax.
* http://tikiwiki.org/RFCWiki An RFC Draft for wiki syntax.
* http://lab.lolipop.jp/fswiki/wiki.cgi/wikistandard An attempt to establish a standard wiki syntax (for Japanese language)
* http://lab.lolipop.jp/fswiki/wiki.cgi/wikistandard An attempt to establish a standard wiki syntax (for Japanese language)
 +
* http://daringfireball.net/projects/markdown/basics This looks like it solves the problem (mostly).
== Summary ==
== Summary ==

Revision as of 11:31, 1 March 2006

Contents

wiki formats

Authors

Intro

Ian Hickson recently lamented to me that:

"I have yet to find a wiki that has both a nice syntax (i.e. one that looks 
like text/plain as opposed to one that looks like just another obscure 
markup language -- if you're going to use markup, why not just use HTML 
in the first place), and that produces semantic markup (as opposed to 
having tags for "bold" and "italics")."

And I have to kind of agree with him. My experience with current wiki formats is that they haven't done that good a job of "paving the cowpaths", that is, taking what people write in plain text documents, and interpreting them as structure, rather than inventing new text conventions (e.g. equal signs for headings?!?) and getting people to learn them.

This page is an attempt to catalog/document current wiki and wiki-like text formats to see if there is any chance of solving this problem.

Technically a wiki format would not be a microformat because it is not expressed in XHTML building blocks. However, many of the other principles of microformats can be applied to perhaps come up with a better solution that what wikis use today (since they all seem to use their own variant formats anyway).


wiki software

MediaWiki

What you're using now.

MoinMoin

What the Technorati Developer's Wiki uses. Starting with v1.3.2, MoinMoin ships with reStructuredText too.

Kwiki

Tiki Wiki

TikiWiki Syntax Reference and Formatting Guide

Important Syntax:

phpwiki

Introduction and Syntax Rules.


Midgard Wiki (net.nemein.wiki)

Other Resources

Should plain text formats from other non-wiki systems be included in this exploration? What about phpbb codes? Or certain blogging tools? What about Almost Free Text ( Syntax Overview ) and other plain text processing tools? There is a breed of hybrid wiki-blog systems like http://www.backpackit.com and http://www.basecamphq.com both by 37signals.

Extra-wiki Formatting Conventions

Live Chats

This includes IRC, and sundry chat services such as AIM. There are several popular conventions to indicate a low level of formatting in plain text in various chat services. Text in between a pair of * is understood to either be an emotion or action (eg *grin*) or *emphasized* (perhaps equivalent to bolding). Text in between a pair of /forward slashes/ is many times understood to carry an italicized meaning. Text in between a pair of _underscores_ is understood to be underlined.

For example, the syntax used by the Yarr (☠) in-Wiki chat system.

Other Standards Efforts

Summary

Apparently most wikis use a * to indicate bulleted lists. Nesting works intuitively. New paragraphs are often indicated with newlines. Several schemes uses capitalized JoinedWords to indicate an internal link, and square brackets [ ] to indicate an external link. Common problems include unexpected failure to handle nesting within certain syntax, competing formatting rules, varying degrees of semantic meaning, and arbitrary formatting codes.

Asterisks to handle unordered lists and pound signs for numbered lists probably work pretty nicely. It's common to use asterisks for lists in plain text formatting, and using a pound sign typically means "a number", and lets the user know that the system will automatically enumerate the following points. However, indicating that the following line should match the indentation of the preceeding line involves strange notation. Unfortunately, arbitrarily blocked elements such as a simple box will break the nesting and continued parsing of list items several wikis.

Likewise, although one doesn't often see exclamation points used to convey that a given line is a heading, this might work nicely as well. An exclamation point indicates importance and emphasis; having it at the beginning of the line is rare, makes the interface to the nesting behavior monotonous because it is the same as the lists, and seems just as natural (to this writer) as filling the succeeding line with dashes or equals. It also makes a lot more sense than surrounding the headline text with equal signs.

Square brackets are used in most wikis to indicate a link of some kind. However, some wikis split links into external and internal, creating a modal interface to publishing links. Furthermore, despite the standard JoinedCapitalizedWords to create an internal link (and/or create a new page), wiki systems freely allow users to ignore the convention by allowing varied alternate linking methods. An additional failing of internal linking schemes is is that wikis are many times a part of a larger content management system, and full "external" links are required anyway in order to reach components of the site. In plain text documents, it is more common to see a full url accompanied with some explaining text. Of the wikis that allow for a natural rendering of urls as links, they also allow a specialized convention to allow for the substituted text to point to the url. Perhaps a future solution would abolish the internal/external modality, parse in-line urls, and include a simple option for text substitution. For example: "http://www.google.com(Google) is a great search engine." would show up as: "[http:www.google.com Google] is a great search engine."

wiki formats

straw proposals

What Ian uses in his text/plain documents:

first level heading - followed by a line starting with equal signs "="
=============================================
second level heading - followed by a line starting dashes "-"
--------
THIRD LEVEL HEADING - ALL CAPS ON A LINE
 1. Here is one ordered list item
 * Here is an unordered list item
_at the moment_
| This is a quote
| and a second line
 -- http://example.com/quotation/

Open issues:

wiki-formats was last modified: Wednesday, December 31st, 1969

Views