Wiki syntax examples

From Piclab

This page is intended to be a simple overview-by-example of the more formally defined wiki syntax proposal, laid out in the same format as Wikipedia's help pages.

It should be far more powerful than the existing syntax, despite the complete elimination of all residual HTML, and much simpler.

The major modifications to take note of are the new << >> syntax for embedded images, inclusions, variables, comments, and other extensions; and the (( )) syntax for style tags.

Note: This is a further change from the earlier proposal. It became clear that alphabetic names were needed for both classes and IDs in the style tags, so they are now introduced by three-character sequences with a "." or "#" after the parens. This eliminates the problem of collision with natural double parens, allowing them to be used for this purpose, and eliminating the curly braces that a lot of commentors didn't like.

While this document describes a new syntax, it is obviously written in the old syntax, so don't look at the source for details as you would the regular Wikipedia help page.

Likewise, it is not nearly so comprehensive as the Wikipedia article, because it's not meant to be. You should be able to extrapolate more details from the examples given.

Table of contents
1 Sections, paragraphs, lists
2 Links
3 Inclusions
4 Text formatting
5 Styles
6 Tables
7 Metadata
8 Character entities
9 Miscellaneous

Sections, paragraphs, lists

No major changes here, except that newlines within lists are now treated consistently with newlines in paragraphs, single-"=" headings are specifically deprecated, and new linebreak syntax.

Desired effect Code

Headings divide text into sections.

First-level heading

Second-level heading

Third-level heading 

== First-level heading ==
=== Second-level heading ===
==== Third-level heading ====

(Five levels allowed)

A single newline has no effect on the layout.

But an empty line starts a new paragraph.

Line breaks can be forced
with double-backslash. 

A single
newline
has no
effect on the
layout.

But an empty line
starts a new paragraph.

Line breaks can be forced \\
with double-backslash.
  • Lists are easy to do:
    • start every line with a star
      • more stars means deeper levels
  • A newline
  • in a list does not end the list.
  • But a blank

line does.

  • You can also
    force line breaks. 
* Lists are easy to do:
** start every line with a star
*** more stars means deeper levels
* A newline
* in a list
//does not// end the list.
* But a blank

line does.

* You can also \\ force line breaks.
  1. Numbered lists are also good
    1. very organized
    2. easy to follow
  2. A blank line

marks the end of the list.

  1. New numbering starts
  2. with 1. 
# Numbered lists are also good
## very organized
## easy to follow
# A blank line

marks the end of the list.

# New numbering starts
# with 1.
  • You can even do mixed lists
    1. and nest them
      • like this. 
* You can even do mixed lists
*# and nest them
*#* like this.
Definition list 
list of definitions
term
the term's definition--these are also ended

by a blank line.

Ommitting the term is a quick way to indent a line
These can be nested
multiple levels. 
; Definition list : list of definitions
; term : the term's definition--
these are also ended

by a blank line.

: Ommitting the term is a quick way to indent a line
:: These can be nested
::: multiple levels.

IF a line of plain text starts with a space THEN
  it will be formatted exactly
    as typed;
  in a fixed-width font;
  lines won't wrap;
ENDIF

IF a line of plain text starts with a space THEN
  it will be formatted exactly
    as typed;
  in a fixed-width font;
  lines won't wrap;
ENDIF

A line of four or more hyphens

creates a horizontal rule. 

A line of four or more hyphens
----
creates a horizontal rule.

Links

No major changes here, except that embedded images are removed, and double-brackets are now used for external links as well, and have the same pipe syntax (although the default presentation will be different, using the auto-counter).

Desired effect Code

Sue is reading the wiki syntax proposal, at section wiki syntax proposal#markup. 

Sue is reading the [[wiki syntax proposal]].
at section [[wiki syntax proposal#markup]].

Links to external pages like http://piclab.com must begin with the "http", "ftp" or other standard access method. Many other standard prefixes identify namespaces within this wiki, other languages, or other wikis, like fr:Train, wikipedia:Train. This: fileaname.jpg is a link to the description page of an uploaded file. 

 Links to external pages like [[http://piclab.com]] must begin
 with the "http", "ftp" or other standard access method.
 Many other standard prefixes identify namespaces within this
 wiki, other languages, or other wikis, like [[fr:Train]],
 [[wikipedia:Train]].
 [[File:filename.jpg]] is a link to the description page
 of an uploaded file.

Particular wikis may have other "magic" links like RFC 2048, ISBN 0123456789X. ISO-format dates like 2005-06-01 and 07-03 will be formatted based on user preferences. 

 Particular wikis may have other "magic" links like
 RFC 2048, ISBN 0123456789X.
 ISO-format dates like [[2005-06-01]] and [[07-03]] will
 be formatted based on user preferences.

The text of the link can be different from the target title, like this (http://piclab.com). Suffixes are blended into the link text: genes, suffixed. Links to Nonexistent pages will appear differently. (Can't render titles with current software). 

 The [[Lee's Wiki|text]] of the [[hypertext|link]] can be
 different from the target title, like [[http://piclab.com|this]].
 Suffixes are blended into the link text: [[gene]]s, [[suffix]]ed.
 Links to [[Nonexistent page]]s will appear differently.
 Popup titles are third argument: [[Vanilla ice cream|ice cream|A great recipe]].

Links with a pipe character with no text will create text that is the same as the link, but with namespaces, parentheticals, and HTTP access prefixes removed. For example, Train, Mars, piclab.com. 

 Links with a pipe character with no text will create text
 that is the same as the link, but with namespaces, parentheticals,
 and HTTP access prefixes removed.
 For example, [[Wikipedia:Train|]], [[Mars (god)|]], [[http://piclab.com|]].

Arguments can be named explicitly if desired for clarity: Home page, Piclab (http://piclab.com), (Can't render titles with current software). 

 Arguments can be named explicitly if desired for clarity:
 [[target=Lee's Wiki|text=Home page]], [[text=Piclab|target=http://piclab.com]],
 [[target=Vanilla ice cream|text=ice cream|title=A great recipe]].

Inclusions

This is the major change in syntax: all inclusion-like things, including extensions like math, embedded images and other media, comments, nowiki, variables, etc., now share a single syntax. I've eliminated the syntactical whitespace as well.

Desired effect Code

Embedded image: Image:pl_bullet.png. Additional arguments specify alternate text, caption, height, etc. May be specified by name for clarity or in order to omit some: small logo, (can't do titles with current software),

Logo
Logo

Note: alignment, height, width, and other attributes are done with styles, as shown later. 

Embedded image: <<image|pl_bullet.png>>.
Additional arguments specify alternate text, caption, height, etc.
May be specified by name for clarity or in order to omit some:
<<image|pl_bullet.png|small logo>>,
<<image|file=pl_bullet.png|alt=small logo|title=Piclab logo>>,
<<image|file=pl_bullet.png|frame|left|width=5em|caption=Logo>>.
Note: alignment and other attributes are done with styles,
as shown later.

All inclusions may be optionally specified on multiple lines:

Logo
Logo
 
All inclusions may be optionally specified on multiple lines:


 <<begin-image>>
 file=pl_bulet.png
 frame
 width=5em
 caption=Logo
 <<end>>

In multiple-line extensions, extra text in the begin/end tags themselves is treated as commentary and removed. (Can't show this with current software). 

In multiple-line extensions, extra text in the begin/end
tags themselves is treated as commentary and removed.


 <<begin-applet|-- This applet simulates Conway's Life game>>
 applet=conway_life.class
 size=400x300
 pattern=none
 <<end Life applet>>

Built-in extensions include "raw", which renders its contents **exactly** as //typed// without interpreting markup, the "!" comment extension, which just removes its contents (for making comments), and "math" for typesetting equations: \sum_{n=0}^\infty \frac{x^n}{n!}.

There are also built-in variables like 12 and http://www.piclab.com. 

Built-in extensions include "raw", which renders its contents
<<raw|**exactly** as //typed// >>without interpreting markup,
the "!" comment extension, which just removes its contents
(for making comments<<!like this>>), and "math" for typesetting
equations: <<math|\sum_{n=0}^\infty \frac{x^n}{n!}>>.

There are also built-in variables like <<currentmonth>> and <<server>>.

Finally, extensions can be used to include templates, which are pre-written pieces of text (possibly with variables) intended to appear in multiple articles: This article is a stub. You can help by adding to it (http://www.piclab.com/lee/index.php?title=Wiki_syntax_examples&action=edit).

Variables may be passed in to the template: Sample template; first argument is "xxx", named argument is "yyy".

And they may be specified in multiple lines as well:

Sample template; first argument is "xxx", named argument is "yyy". 

Finally, extensions can be used to include templates,
which are pre-written pieces of text (possibly with variables)
intended to appear in multiple articles:
<<include|stub>>

Variables may be passed in to the template:
<<include|example|xxx|named=yyy>>

And they may be specified in multiple lines as well:


 <<begin-include|example|-- Should be identical to first example>>
 positional=xxx
 named=yyy
 <<end>>

Within the template text, variables are called by name or by position, and possibly with defaults. (This won't be demonstrated in article text, because it's only in the template). In the code to the right, the first example is replaced by the argument named "file", wherever it occurs in the template call. The second example is replaced by the variable named "text" if it exists and is nonblank, otherwise by the second argument given, regardless of name. Finally, the tihrd example is replaced by the variable named "text" if it is nonblank, otherwise by the third argument; if that too is blank, then by the default text "default". 

 <<$file>>
 <<$text|$2>>
 <<$text|$3|default>>

Text formatting

All of these can be done using the general-purpose style mechanism below, but they are used so frequently that a shortcut syntax is justified. Also, not having any words in the markup makes them much more readable and easier to edit.

Desired effect Code

There are shortcuts for entering boldface text, italic text, typewriter text, superscript, and subscript. Most of these can be nested as well. 

 There are shortcuts for entering **boldface text**,
 //italic text//, $$typewriter text$$, ^^superscript^^,
 and __subscript__.
 Most of these //can be **nested** as well//.

Because short subscripts and superscripts are so common, their shortcuts are terminated by spaces, puctuation, and each other, like this: xFred23 is ... To nest them, you must use styles or math: x35, x^{3^5}. 

 Because short subscripts and superscripts are so common,
 their shortcuts are terminated by spaces, puctuation, and
 each other, like this: x__Fred^^23 is ...
 To nest them, you must use styles or math:
 x((.sup|3^^5^^)), <<math x^{3^5}>>.

Styles

This is wholly new, and log needed. Separating style from content makes it easier for newcomers to edit article text while at the same time giving power users more control over article appearance--a big win-win.

Desired effect Code

Individual words or short phrases are enclosed within style markers, and must appear entirely within a single line of input text. If no text is enclosed, the style marker applies to exactly one word. These may be not be nested, though character-style shortcuts may appear within them.

Links and images are treated

as "words" in this regard. 

 Individual ((.big|words)) or ((.u|short phrases)) are enclosed
 within style markers, and ((.i))must appear entirely within a single
 line of input text.
 If no text is enclosed, the style marker applies to exactly one word.
 These ((.i|may **not** be nested)), though character-style shortcuts
 may appear within them. 
 ((.left))<<image|pl_bullet.png>>Links and images are treated
 as "words" in this regard.

The first word within the style marker is the style tag, and is in one of two forms: class tags beginning with "." are non-unique, and refer to a class of objects with the same style; ID tags beginning with "#" are unique, and refer only to the specific object so tagged. 

 The first word within the style marker is the style ((.i))tag, and is in
 one of two forms: ((.ub))class tags beginning with "." are non-unique,
 and ((.ub|refer to)) a ((.i))class of objects with the same style;
 ((#x3))ID tags beginning with "#" are ((#z7|unique)),
 and refer only to the object so tagged.

Attached stylesheet: 

 .ub { font-weight: bold; text-decoration: underline; }
 #x3 { color: red; }
 #z7 { color: green; }

Many styles are built in, such as italics, boldface, typewriter text, underline, big text, small text, subscript, superscript, left-, right-, and center-alignment, and others. 

 Many styles are built in, such as ((.i))italics, ((.b))boldface,
 ((.tt|typewriter text)), ((.u))underline, ((.big|big text)),
 ((.small|small text)), ((.sub))subscript, ((.sup))superscript,
 left-, right-, and center-alignment, and others.

Larger blocks of text such as paragraphs and lists can be tagged with styles using either the multi-line "begin" syntax, or by placing a marker by itself on a line, making it refer to the following paragraph (or other logical block of text).

This paragraph will be centered.
This one is right-justified and in big text
  1. This list
  2. should use
  3. Roman numerals

(Can't do this with current software) 

 Larger blocks of text such as paragraphs and lists can be tagged
 with styles using either the multi-line "begin" syntax, or by
 placing a marker by itself on a line, making it refer to the
 following paragraph (or other logical block of text).

 ((.center))
 This paragraph will be centered.

 ((begin-#z7|-- comments are allowed here))
 This one is right-justified and in small text
 ((end))

 ((.mylist))
 # This list
 # should use
 # Roman numerals

Attached stylesheet ("center" is built in): 

 #z7 { text-align: right; text-size: big; }
 .mylist { list-style-type: upper-roman; }


Tables

This is based on Magnus's syntax, but all HTML is eliminated in favor of external styles, existing syntax is simplified a bit, and features are added for spanning.

Desired effect Code

A simple wiki table looks like this:


Simple Table
Fruit Color
banana yellow
orange orange
lime green


Any text on the first line is taken to be a caption. Table cells begin with "|"; they may be combined in a line, or on separate lines. Cells beginning with "|!" are header cells. Rows are separated by "|-". 

 A simple wiki table looks like this:

 {| Simple Table
 |! Fruit |! Color
 |-
 | banana | yellow
 |-
 | orange | orange
 |-
 | lime
 | green
 |}

Styles can be attached to the table, individual cells, rows, or columns. Columns are given implicit names "col1", "col2", etc.

A more complex table
Name Wife Children
Fred Flintstone Wilma 1
Barney Rubble Betty 1 
 Styles can be attached to the table, individual cells,
 rows, or columns.
 Columns are given implicit names "col1", "col2", etc.

 ((#id5))
 {| A more complex table
 ((.toprow))
 |! Name           |! Wife  |! Children
 |-
 | Fred Flintstone | Wilma  | 1
 |-
 | Barney Rubble   | Betty  | 1
 |}

Attached stylesheet: 

 #table1 { background-position: center; border-width=1pt; }
 .toprow { background-color: #9999FF; }
 #id5#col3 { text-align: right; }

To span rows or columns, mark the empty cells: cells beginning with "|<" are merged with the cell to the left; cells beginning with "|^" are merged with the cell above.

1 2
3 4 
 To span rows or columns, mark the empty cells:
 cells beginning with "|<" are merged with the cell
 to the left; cells beginning with "|^" are merged
 with the cell above.

 {|
 |   1   |<      |   2
 |-
 |   3   |   4   |^
 |}

Metadata

Some things currently part of wiki syntax will be moved to metadata. That is, a collection of data separate from, but associated with, the article itself. These include:

  1. Redirects: Metadata indicates that the article is a redirect, and to which page it goes. The article text itself is entirely ignored.
  2. Local styles.
  3. Presence, absence, and configuration of an article table of contents.
  4. Article source and copyright information
  5. Article categories
  6. Language links

The software wil have to have a means of entering this; perhaps an "about" or "info" tab leading to an input form.

Character entities

HTML character entities like &amp; and &#x20; are ignored by the parser, so they can be used, for example, to put pipe characters in table cells, curly braces within a style tag, or just for escaping a character or two without using "raw".


Miscellaneous

I really don't like the auto-numbered external links. I'd like to eliminate them, but I'm concerned that lots of articles may use them for references in a way that would be hard to translate.

I would, however, like to add some feature for simplifying internal notes and references. Even something simple like automatically superscripting the text of a link if that text is a number would be nice. But something more elaborate like making "footnote" a specific link type that creates the notes section automatically might be nice too. I doubt that can be done cleanly, though, because (a) it puts the text of the note in the place where it is first referenced rather than at the end, and that might confuse new editors, especially a long note in the middle of a sentence; and (b) it makes repeating references impossible without giving them IDs, which defeats the purpose of simplifying them.

Another idea might be something that magically recognized a numbered list in the notes or references section and renumbered links to it when changes are saved. That will take some thought.

Retrieved from "http://www.piclab.com/lee/index.php/Wiki_syntax_examples"