wiki-formats: Difference between revisions

From Microformats Wiki
Jump to navigation Jump to search
m (Reverted edits by DomliTroco (Talk) to last version by ChristopheDucamp)
 
(28 intermediate revisions by 18 users not shown)
Line 4: Line 4:


* Tantek Çelik
* Tantek Çelik
* Ben West


== Intro ==
== Intro ==
Line 33: Line 34:
** use multiple "*", e.g. "** " for 2nd level, for nested unordered lists.
** use multiple "*", e.g. "** " for 2nd level, for nested unordered lists.
* ordered lists
* ordered lists
** start a line with "# " and it will put it into an unordered list.
** start a line with "# " and it will put it into an ordered list.
** use multiple "#", e.g. "## " for 2nd level, for nested unordered lists.
** use multiple "#", e.g. "## " for 2nd level, for nested ordered lists.
* headings
* headings
** prefix and suffix with "=" for level 1 heading, "==" for level 2 heading etc.
** prefix and suffix with "=" for level 1 heading, "==" for level 2 heading etc.
* literal
* literal
** use <pre> ... </pre> tags
** use
* [[mediawiki-mark-up-issues|mediawiki mark-up issues]]


=== MoinMoin ===
==Comments==


What the [http://developers.technorati.com/ Technorati Developer's Wiki] uses.
Guy Fraser: I assume you've not seen Confluence from www.atlassian.com - what you describe above is exactly how Confluence wiki notation works. Confluence has one major benefit over MediaWiki in that it has decent navigation tools - you can, for example, see a page index, site map, etc. In media wiki, unless you know what you are searching for or unless someone makes a link in a prominent place, content tends to dissapear unless you know what to search for. [unsigned comment from [[User:Aubergine10]] ]


=== Kwiki ===
JimMahoney: http://www.wikicreole.org is working on a common wiki markup language - the discussion there seems closely related to the issues raised here.
 
* See http://www.kwiki.org/
 
=== Tiki Wiki ===
[http://doc.tikiwiki.org/tiki-index.php?page_ref_id=268 TikiWiki Syntax Reference] and
[http://doc.tikiwiki.org/tiki-index.php?page=Formatting%20Standards Formatting Guide]
 
Important Syntax:
 
* Lists
** * Creates an unordered list.
** # Creates a numbered list.
** ;term:definition creates a term and definition list.
** Features include nesting in a predictable manner, sections that can hide/display with a +/- symbol, and line continuation after breaks.
* Links
** JoinedWords indicate an internal wiki link.
** ((Words|Description)) inside parenthesis also indicates an internal wiki link and can include spaces and non-standard wiki link conventions.  A pipe delimits the text to be used for the link.
** ))JoinedWords(( can escape the link parsing.
** External links go inside square brackets [ ] with the same convention regarding the descriptive text.  Many features of this wiki also allow options to be passed, eg. nocache, after a pipe.
* Images
**  {img src= width= height= align= desc= link= }
* Text formatting
** Bolding is done by placing text in between a pair of double underscores: __bolded text__
** Text is centered by placing text in between two colons: ::centered text::
** Text is colored by delimiting the color name and the text with a colon surrounded by a pair of double tildes. ~~blue:text~~
** Text is italicized by surounding the text with a double pair of single quotes: <nowiki>''italicized''</nowiki>.
** The syntax for monospaced/teletype text is: -+monospaced text+-
** Underlined text is indicated with 3 equal signs: ===underlined text===
** Text can be put in a simple box by surrounding it with the carrot: ^boxed text^
* Headings
** Headings are indicated by the presence of an exclamation mark at the beginning of the line: !My heading.  Sub headings and level of nesting is indicated by the number of exclamation marks. (Same way that lists nest.)  This does carry semantic purpose in the TikiWiki documentation and the maketoc module uses this feature in order to make tables of contents.
 
=== phpwiki ===
[http://phpwiki.sourceforge.net/phpwiki/HowToUseWiki Introduction]
and [http://phpwiki.sourceforge.net/phpwiki/TextFormattingRules Syntax Rules].
 
* Formatting (copied from http://phpwiki.sourceforge.net/phpwiki/TextFormattingRules, edited to make a list)
** Emphasis: _ for italics, * for bold, _* for both, = for fixed width.
** Lists: * for bullet lists, # for numbered lists, Term:<new-line> definition for definition lists.
** Preformatted text: Enclose text in <nowiki><pre></pre></nowiki> or <verbatim></verbatim>.
** Indented text: Indent the paragraph with whitespaces.
** References: JoinCapitalizedWords or use square brackets for a [page link] or URL <nowiki>[http://example.com]</nowiki>.
** Preventing linking: Prefix with "~": ~DoNotHyperlink, name links like [text | URL].
** Misc: "!", "!!", "!!!" make headings, "%%%" or "<br>" makes a linebreak, "----" makes a horizontal rule.
** Allowed HTML tags: b big i small tt em strong abbr acronym cite code dfn kbd samp var sup sub
 
== Other Resources ==
* See http://c2.com/cgi/wiki?WikiEngines for a list of known wikis.
* See http://tavi.sourceforge.net/WikiEngines/ComparingWikis for a table comparing wiki features (no syntax information)
 
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 ( [http://www.maplefish.com/todd/aft-refman.html#Syntax%20Overview Syntax Overview] ) and other plain text processing tools?
 
== Other Standards Efforts ==
* http://tikiwiki.org/RFCWiki An RFC Draft for wiki syntax.
 
== 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.
 
== wiki formats ==
 
* [http://www.kwiki.org/?WaflProposal WAFL - Wiki Abstract Formatting Langauage]
 
== straw proposals ==
 
What Ian uses in his text/plain documents:
 
* h1:
**
<pre>
first level heading - followed by a line starting with equal signs "="
=============================================
</pre>
* h2:
**
<pre>
second level heading - followed by a line starting dashes "-"
--------
</pre>
* h3:
**
<pre>
THIRD LEVEL HEADING - ALL CAPS ON A LINE
</pre>
* p:
** a blank line to start and finish
* ol / li
** a line starting with space then a number followed immediately by a period, e.g.
<pre>
1. Here is one ordered list item
</pre>
** note that such list items may be separated by blank lines. 
** note that paragraphs within a list item will be indented as much as the text after the list item marker.
** list is terminated by a non-blank line that *doesn't* start with space then a number then a period, and is outdented from where list item paragraphs are.
* ul / li
** a line starting with space then an asterisk then at least one space, e.g.
<pre>
* Here is an unordered list item
</pre>
** same notes apply respectively as those for ordered list items above.
** nested unordered list items are similar, except that their marker is further indented, and in addition to "*", other list item markers may be used such as "+" and "-".
* pre / code
** some amount of nesting with whitespace.  pre / code.  it's not clear what type of code (e.g. HTML or CSS).
* em
** text surrounded by a single adjacent underline on both sides, e.g.
<pre>
_at the moment_
</pre>
* blockquote and cite attribute
** a set of lines that being with "| ", and after the last one, a line that starts with " -- ", followed by the citation URL, e.g.:
<pre>
| This is a quote
| and a second line
-- http://example.com/quotation/
</pre>
 
Open issues:
* What's this?
** <code>-*- Mode: text; -*-</code> ''It's the Emacs mode line. Just ignore anything starting with one or more spaces and then having the form -*- ... -*-''
* how do you encode in text/plain the semantics of:
** strong ''Use *stars* instead of _underscores_''
** dfn
** dl/dt/dd
** h4, h5, h6 ''There is no H4 in this format. Only H1-H3. Just like HTML has no H7, and is limited to H1-H6.''
** table / thead, tbody, tfoot, caption / tr / td, th ''I have some pages that do tables, you just do an actual ASCII art table with proper ASCII art lines''
** hyperlinked text ''text/plain has no hyperlinks, so I always put them on the next line (pre/code style)''
** hyperlink relationships (rel attribute on hyperlinked text)
** address (possibly the "Author: " line?)
** inline code

Latest revision as of 18:14, 20 December 2008

wiki formats

Authors

  • Tantek Çelik
  • Ben West

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.

  • paragraphs
    • blank line creates a new paragraph
  • unordered lists
    • start a line with "* " and it will put it into an unordered list.
    • use multiple "*", e.g. "** " for 2nd level, for nested unordered lists.
  • ordered lists
    • start a line with "# " and it will put it into an ordered list.
    • use multiple "#", e.g. "## " for 2nd level, for nested ordered lists.
  • headings
    • prefix and suffix with "=" for level 1 heading, "==" for level 2 heading etc.
  • literal
    • use
  • mediawiki mark-up issues

Comments

Guy Fraser: I assume you've not seen Confluence from www.atlassian.com - what you describe above is exactly how Confluence wiki notation works. Confluence has one major benefit over MediaWiki in that it has decent navigation tools - you can, for example, see a page index, site map, etc. In media wiki, unless you know what you are searching for or unless someone makes a link in a prominent place, content tends to dissapear unless you know what to search for. [unsigned comment from User:Aubergine10 ]

JimMahoney: http://www.wikicreole.org is working on a common wiki markup language - the discussion there seems closely related to the issues raised here.

Retrieved from "http://microformats.org/wiki/index.php?title=wiki-formats&oldid=36168"