The Markup Language

posted November 21, 2009; updated December 27, 2013

The markup language specification has six parts:

Special Character patterns	All special character patterns used to markup text - basic shortcuts
Link and Image URI formats	Network protocol, symbolic link, and anchor formats of reference to links and images - shortcuts
Decorators	The special inline decorator and block decorator markup, and selectors available - shortcuts for decoration arguments: classes, attributes, and styles
Tag Declarations	The special tag declarations, and selectors available - other html formats
Decoration argument formats	The standard decoration argument 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 //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 shortcuts
=	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 shortcuts
\\	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 - these are stripped out during parsing
```comment...	comment	3 backticks end of line to place comment in the source - comments are stripped out during parsing
Links and Images shortcuts
[[...|...|...]]	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 shortcuts
* **	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 - shortcuts for classes, styles, and attributes
% ... %	inline decorator	opening and closing percent sign, containing selector and decoration 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 decoration arguments, start of line
Advanced - tag declarations for other html shortcuts
[\t\x20]*(:? ... :) ... [\t\x20]*(:?end:)	block tag declaration	opening tag at start of a line, containing tagname and decoration 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
%=? ... % ... %=%	inline tag declaration	opening %= anywhere in the line, containing tagname and decoration arguments; closing markup %=% (optional) before the end of the line if only part of the line is to be marked; ? = tagname
[\t\x20]*(::? ... :)	void block tag declaration - opening tag only; no content	opening tag at start of a line, containing tagname and decoration arguments; ?=tag name;[\t\x20]*=tab/space-chars (optional)
%==? ... %	void inline tag declaration - opening tag only; no content	opening %== anywhere in the line, containing tagname and decoration arguments; ? = tagname
Advanced - other specialized markup
<< ... | ... >>	macro, text optional	opening and closing angle brackets, containing macro name and decoration 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; obtained with $dataobject = $wiki->get_metadata();
{{##? ... ##}}	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 (backtick)	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

Decorators provide a uniform way of applying style classes, style-rules, and attributes to the objects created by the basic markup. They provide a thin (and simplified) veneer over HTML.

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:|. All decorators have to be placed right in front of the opening markup for the objects they decorate.

Within their delimiters, inline and block decorators have identical markup structures:

%selector decoration_arguments%
|:selector decoration_arguments:|

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

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. 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).

Tag Declarations

The markup supports four kinds of tag declarations: block, void block, inline and void inline. "void" means an opening tag only, with no content. The markup summary is:

(:selector decoration_arguments:) content // block element
   more content
(:selectorend:)
(::selector decoration_arguments:) // void block element
%=selector decoration_arguments% content %=% // inline element
%==selector decoration_arguments% // void inline element

This markup not only avoids limitations for the sophisticated author, but also supports brevity and consistency of markup.

See Tag Def Extensions for ways of getting and setting the set of tags that your client software can control.

Block Tag Declarations

block declarations
Markup Tag	Meaning	HTML Tag
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
colgroup	column group	colgroup
col	column (but use void version instead)	col
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 - deprecated)
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, the markup provides block declarations. These are a thin veneer over html. The general syntax for block declarations is

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

The tagname is required, and must be one of the tagnames listed in the tables at the right or below. 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 decoration arguments are optional, but are available to set style classes, style rules, or attributes of the underlying HTML element. Action 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 markup structures made available, like quick tables, lists, etc.

The tags available for block declarations are listed at the right and below.

more block declarations
Markup Tag = HTML Tag	Meaning	Markup Tag = HTML Tag	Meaning
HTML 5 semantic tags		media tags
figure	embedded figure	map
figcaption	figure caption	object	also allowed as inline tag
article	self-contained content	audio
address	content author address	video
aside	related sidebar	canvas
footer	page footer	form tags
section	document section	form
header	page header	output
hgroup	header group	datalist
nav	navigation section	muster widget tags
main	main content	reserved
details	a disclosure widget	mw-module
dialog	popup dialog	mw-widget
summary	summary of details	mw-settings
HTML 5 ruby tags		mw-marker
ruby	ruby annotation (East Indian languages)	muster widgets is a javascript library planned by the author of this markup
rt	explanation of ruby characters
rp	ruby base text

Inline Tag Declarations

Inline tag declarations are markup for inline tags:

some content %=tagname decoration_arguments%some content%=% <- closing markup for inline tags

The following tags are supported (natively). Tags are filtered at compile time according to this list. If a tag is used that is not supported, the raw markup is output instead.

inline tag declarations
Markup Tag = HTML Tag	Meaning	Markup Tag = HTML Tag	Meaning
appearance		specialized
b	bold	a	anchor
i	italic	img	image
big		q	quote
small		span
ins		button
del		progress
abbr		meter
cite		time
sub	subscript	object	embedded
sup	superscript	bdi	bi-directional isolation
mark		bdo	bi-directional over-ride
phrase elements		form
code		select
dfn	definition	option	for select
em	emphasis	label
strong		textarea
kbd	keyboard	misc
samp	sample code	command	command button html5
var	variable

Void Block Tag Declarations

Void tag declarations allow void tags (single tag - no content) markup.

(::tagname decoration_arguments:)

hr	horizontal rule
area	for map
param	for object
source	for audio
track	for video
col	col spec for colgroup

Void Inline Tag Declarations

Void tag declarations allow void tags (single tag - no content) markup.

%==tagname decoration_arguments%

br	line break
wbr	word break (html5)
img	image
input	form
keygen	form
embed	container for external application

Decorator and Tag Declaration Decoration Argument Formats

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

Argument	Format	Description	Target
textvalue (class name)	discreet textual value	single name containing a character, followed by characters, numerals, underscore (_), or dash(-)	HTML element class attribute
property (style rule)	colon-separated 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	equals-separated 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 decoration argument, but for Decorators (not for Tag Declarations) there must be at least one decoration argument.

• Classnames (unless they are registered action 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 action 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.

Action 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 action classes. Action classes serve as automation shortcuts to achieve desired effects. Action properties are analagous to action classes (propertymethod:methodarguments) except their format allows passing of arguments to the methods. Property methods are also registered by client software, and should be unset as html properties during processing 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 for 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").

---