The SimpleWiki Markup Language

posted November 21, 2009; updated June 18, 2011

The SimpleWiki markup language (swml) specification has six parts:

Special Character patterns	All special character patterns used to markup text
Link and Image URI formats	Network protocol, symbolic link, and anchor formats of reference to links and images
Decorators	The special inline decorator and block decorator markup, and selectors available
Block Declarations	The special block declarations, and selectors available
Argument formats	The standard formats used to pass data to underlying html elements through decorators and declarations
Macros	General markup available for client-defined macro procedures. The language specification does not define any macros

Specification

Marking up content so that it will look good involves using a few special characters (like forward slashes for //emphasis// for emphasis, and a lot of decorators. Decorators are sequences of characters that provide detailed style information to the markup engine. The core of the language is creole 1.0. Decorators and Declarations (and a few other things) are extensions.

SimpleWiki Special Character Patterns

Character Pattern	Usage	Description
Basic markup - common
=	heading	equals signs, 1 to 6 of them, start of line
	paragraph	blank line above text
// ... //	emphasis (italic)	2 forward slash pairs, open and close
** ... **	strong (bold)	2 asterisk pairs, open and close
----	horizontal rule	four dashes, alone on line
Basic markup - occasional
\\	line break	2 inline backslashes
~	escape character	tilde; the following character will be parsed as literal
``	line continuation	2 backticks start of line, to make the source more readable
```	comment	3 backticks start of line to leave comment in the source
Links and Images
[[...|...|...]]	link; caption and title optional	opening and closing double square brackets; optional one or two vertical bars
[[#...|...|...]]	anchor link; caption required, title optional	opening double square brackets and hash mark, closing double square brackets; optional one or two vertical bars
[[#...]]	anchor target	opening double square brackets and hash mark, closing double square brackets
{{...|...|...}}	image; caption and title optional	opening and closing double braces; optional one or two vertical bars
Lists and Tables
* **	unordered list	asterisk - one at start of first line; one or more, nested, on following lines[1]
# ##	ordered list	hash mark - one at start of first line; one or more, nested, on following lines
: ... :: ... :: ... :: ...	definition list	colon - one at start of first line; one or more, nested, on following lines; the embedded double colon denotes the end of the term and the start of the description, and is optional. Without the double colon the text is the description.
|...|...|...| etc. |...|...|...| etc.	quick table row	vertical bars - beginning at start of line, plus one for each additional cell, plus closing vertical bar; multiple lines
|=	heading cell (th)	"=" following vertical bar in table row
Decorators
% ... %	inline decorator	opening and closing percent sign, containing selector and arguments, inline
%%	end-of-span-decoration	two percent signs, inline usage: %s ...%...%%
|: ... :|	block decorator	opening and closing mirrored vertical bar and colon, containing selector and arguments, start of line
Advanced
[\t\x20]*(:? ... :) ... [\t\x20]*(:?end:)	block declaration	opening tag at start of a line, containing tagname and arguments; closing tag alone on a later line; ?=tag name; [\t\x20]*=tab/space-chars (optional) for nesting and must match as to count of characters; end signifies closing tag
<< ... | ... >>	macro, text optional	opening and closing angle brackets, containing macro name and arguments, optional vertical bar followed by parsed inline text
{{{...}}}	inline preformatted text	opening and closing triple braces, containing performatted text
{{{ ... }}}	preformatted block	opening triple braces alone on a line, closing triple braces alone on later line; preformatted text in between
```##	metadata	3 backticks followed by two hash marks - first line, followed by arguments interpreted by client software
{{##? ... ##}}	marker	?=name. Markers are extracted and marker objects are listed in an array that can be obtained with $wiki->markerdata() after $wiki->prepare(). Each marker object contains the marker name, its offset, and its decoration.
`	symlink version marker	after a symlink selector for either an image or a link Symlink:selector`version, a backtick followed by a name can be used by a registered symlink handler to find a version of a file. Useful for image sizes for example.

Note that ordered and unordered lists can be nested within each other.

Link and Image URI Formats

The first cell of Link and Image markups consist of a url to the link or image. For links the format can be any one of the three; for images the format can be protocol or symbolic.

Format Name	Format Structure	Notes
Network Protocol Format	protocol://address	standard url format: http, https, ftp, nntp, news, mailto, telnet, file, irc
Symbolic Link Format	Symlink:selector	symbolic links registered by client software; special link Local: is registered by SimpleWiki by default for relative directory addressing; Anchor: is also a default; first character of Symlink must be capitalized
Anchor Format	#selector	key symbolic link 'Anchor' can be registered to deal with html base issues if needed; set target element id attribute to selector
Raw link format	selector	When none of the above are recognized, the raw link is available to be passed to a client-registered raw link handler for interpretation

The special symbolic links Local: and Anchor: are registered by default by the SimpleWiki module. Local is intended to allow relative directory addressing for local references. Anchor is intended to allow on-page links.

See the Module section for details on registering symbolic links, symbolic link handlers, and raw link handlers with SimpleWiki.

In addition, free standing http, https, and mailto addresses will automatically have link markup [[ ... ]] wrapped around them. Other protocols (such as ftp) must escape the forward slashes in the format (like ftp:~//someaddress), or the forward slashes will be interpreted as emphasis markup.

Decorators

There are two kinds of decorators: inline decorators, and block decorators. Inline decorators begin and end with a percent sign %inlinedecorator%, and block decorators begin and end with a mirrored pair of characters (the vertical bar and colon) like this |:blockdecorator:|. Block decorators have to be placed at the beginning of a line. Inline decorators can be anywhere in a phrase or sentence. All decorators have to be placed right in front of the objects they decorate.

Within their delimiters, decorators have identical markup structures:

%selector arguments%
|:selector arguments:|

The selector tells the markup engine what object type the decoration is applied to, and the arguments convey the information about what to apply.

Decorators always have to be right in front of the objects they decorate.

Inline Decorators

There are only four types of inline decorators:

SimpleWiki Inline Decorators
Selector	Target object	Notes	Example
s	span	in front of a sequence of words, closed with %%	%s underline%...%%
l	link	(l=lower case "L") in front of [[link]]	%l newwin%[[...
i	image	in front of {{image}}	%i rframe%{{...
c	code	in front of preformatted text {{{text}}}	%c html%{{{...

Note that the closing markup of two percent signs %% closes the scope of the span (%s ...%) decoration.

Block Decorators

There are quite a few block decorators:

SimpleWiki Block Decorators
Selector	Target object	Example
Paragraph
p	paragraph	|:p font-weight:bold:|...
Dividers
h	heading	|:h section-divider-high:|===...
b	empty block (divider)[2]	|:b spacer dots:|
Lists
ul	unordered list	|:ul list-style-type:square:|* ...
ol	ordered list	|:ol list-style-type:upper-roman start="10":|# ...
li	list item	|:li font-style:italic:|# ... |:ul list-style-type:square:||:li font-style:italic:|* ...
dl	definition list	|:dl ... :|: ...
dt	definition term	|:dt ... :|: ...
dd	definition description	|:dd ... :|: ... |:dl ... :||:dt ... :||:dd ... :|: ...
Tables
table	table	|:table border="1":||...|...|...
tr	table row	|:tr background-color:yellow:||...|...|... |:table border="1":||:tr background-color:yellow:||...|...|...
th	table heading cell	color green applied to second from left cell: |=...|:th color:green:||=...|=... three decorators applied to the same line: |:table border="1":||:tr background-color:yellow:||:th color:green:||=...|=...|=...
td	table data cell	|...|:td color:green:||...|... td decorator usage is identical to th decorator usage
Preformatted Text
pre	preformatted text block	|:pre html:|{{{ ...

Block decorators must be placed immediately in front of the objects that they decorate, and must begin the line. Block dividers are placed on a line by themselves (the block object for block dividers is implicit).

When more than one block decorator is placed in front of an object (like |:table... and |:tr... in front of the same vertical bar), they must be placed in order, from outer object to inner object (for example table block decorator before table row block decorator).

Block Declarations

SimpleWiki block declarations
SimpleWiki Tag	Meaning	HTML element
content blocks
div	generic division	div
blockquote	indented block of content	blockquote
table
table	table	table
caption	caption	caption
thead	table head	thead
tbody	table body	tbody
tfoot	table footer	tfoot
tr	table row	tr
td	table data cell	td
th	column header cell	th
lists
ul	unordered list	ul
ol	ordered list	ol
li	list item	li
dl	definition list	dl
dt	definition term	dt
dd	definition description	dd
dlml (website)
dlwidget	dlml widget	dl:widget
dlsettings	dlml settings	dl:settings
dlmodule	dlml module	dl:module
dlmarker	dlml marker (reserved)	dl:marker

For advanced page layout design, SimpleWiki provides block declarations. These are a thin veneer over html. The general syntax for block declarations is

<tab-or-space-char>*(:tagname arguments:)
...
<tab-or-space-char>*(:tagnameend:)

The tagname is required, and must be one of the tagnames listed in the table at the right. Both opening and closing tags must be at the start of the line. Closing tags must be alone on a line. Opening tags can have content following on the same line to avoid generation of a paragraph block.

The <tab-or-space-char>'s are optional, but are available to allow nesting of blocks, like this:

(:div background-color:red:)
   some content
   (:div margin:20px bacground-color:green:)
      some more content
   (:divend:)
(:divend:)

... where the indents are matching numbers of tab or space characters.

The blocks can be nested in any combination to any (logical) depth. This allows, for example, complex tables inside table cells.

The arguments are optional, but are available to set style classes, style rules, or attributes of the underlying HTML element. Active classes are also available (see below).

Each declared block (and nested declared block) is parsed as a block of content, and so can contain any of the SimpleWiki structures made available, like quick tables, lists, etc.

The tags available for block declaration are listed at the right.

Decorator and Block Declaration Arguments

Arguments are the data values that are passed from the Decorators and Block Decorations to the target objects (meaning the underlying HTML elements). The arguments for all decorators and block declarations have the same structure. There are exactly three formats of argument available in all cases:

Argument	Format	Description	Target
class name	discreet textual value	single name containing a character, followed by characters, numerals, underscore (_), or dash(-)	HTML element class attribute
style rule (aka property)	rulename: rulevalue	rulename follows classname rules; rulevalue always separated by colon (:); rulevalue can be surrounded by single or double quotes	HTML element style attribute
attribute	attributename= attributevalue	attributename follows classname rules; attribute value always separated by an equals sign; attributevalue can be surrounded by single or double quotes	HTML element named attribute

There can be zero to many instances of each format of argument, but for Decorators (not for Block Declarations) there must be at least one argument.

• Classnames (unless they are registered active classes -- see below) are passed directly to the target object's (underlying HTML element) class attribute. When classnames are directly passed through like this they are called style classes.
• Style rules (unless they are registered active properties are passed directly to the target object's style attribute.
• Attributes are passed directly to the underlying target objects as is. Note that the attributes value delimiter that is written by the author is preserved in html generation. This allows JSON arguments to be used for custom attributes.

In this way, SimpleWiki can be viewed as a thin (simplifying) skin over the HTML layer of the web page.

Style classes are any classes defined in css (cascading style sheet) files that are created for the website. Style classes are named collections of style rules.

Active classes are any classnames (registerd as methods by the client application using SimpleWiki) that perform software-based operations on the underlying HTML elements. SimpleWiki contains a number of native active classes. Active classes serve as automation shortcuts to achieve desired effects. Active properties are analagous to active classes {propertymethod:methodarguments} except their format allows passing of arguments to the methods. Property classes are also registered by client software, and should be unset from the processed node decoration after being called to prevent them from being interpreted natively as styles.

Style rules can be any valid CSS style rules.

Attributes can be any valid attributes for the target's underlying HTML element.

It is a generally accepted best practice to rely on logically named style classes as much as possible, to allow for centralized revision of style schemes. The corollary is to avoid explicit style rules as much as possible. In most cases, styling options available through attributes are better implemented using css style rules.

Macros

Macros are registered by client software, and interpreted by callback functions. Macro syntax allows from the macroname, arguments in standard formats, and parsed inline markup to the right of a vertical bar. How these resources are used is up to the callback function. See the Module section for details.

The SimpleWiki module registers one macro by default: quicktoc. This macro uses any markup title as the quick table of contents header, if present (otherwise uses the string "Table of contents").

---