```## tabid=language 
``titletext='Markup language specification' 
``subjecttext='Markup Language Specification'
<<quicktoc>>
== The Markup Language ==
|:p div float:right:|%s smaller%//[[Local:display/article/language|view source markup]]//

|:p posting:|posted November 21, 2009; updated December 27, 2013

The markup language specification has six parts:

|:table standard:||:td width:26%:|
``|[[#patterns | Special Character patterns]] 
``| All special character patterns used to markup text - basic shortcuts |
|[[#links | Link and Image URI formats]] 
``| Network protocol, symbolic link, and anchor formats of reference to links and images - shortcuts |
|[[#decorators|Decorators]] 
``| The special inline decorator and block decorator markup, and selectors available - shortcuts for decoration arguments: classes, attributes, and styles |
|[[#declarations |Tag Declarations]] 
``| The special tag declarations, and selectors available - other html formats |
|[[#arguments |Decoration argument formats]] 
``| The standard decoration argument formats used to pass data to underlying html elements through decorators and declarations|
|[[#macros |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 %l newwin%[[http://wikicreole.org/|creole 1.0]]. Decorators and Declarations (and a few other things) are extensions.

|:h id=patterns:|=== SimpleWiki Special Character Patterns ===

|:table standard width:100%:|
``|:th width:15%:||=Character Pattern
``|:th width:25%:||=Usage 
``|:th width:60%:||=Description |
|:tr background-color:LightGoldenRodYellow:||:th colspan=3 text-align:center:|
``|=**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|
|:tr background-color:LightGoldenRodYellow:||:th colspan=3 text-align:center:|
``|=**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|
|%c html%{{{<code>&#x0060;``comment...</code>}}}|comment|3 backticks end of line to place comment in the source - comments are stripped out during parsing|
|:tr background-color:LightGoldenRodYellow:||:th colspan=3 text-align:center:|
``|=**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 |
``
|:tr background-color:LightGoldenRodYellow:||:th colspan=3 text-align:center:|
``|=**Lists and Tables shortcuts**|
|*\\*~*|unordered list|asterisk - one at start of first line; one or more, nested, on following lines%s footnote%The first list item in a list must have only one star or hashmark. This is to avoid conflict with the two-star //strong// markup%%|
``
|#\\##|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|
|:tr background-color:LightGoldenRodYellow:||:th colspan=3 text-align:center:|
``|=**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|
``
|:tr background-color:LightGoldenRodYellow:||:th colspan=3 text-align:center:|
``|=**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|
|:tr background-color:LightGoldenRodYellow:||:th colspan=3 text-align:center:|
``|=**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|
|%c html%{{{&#x0060;}}}``##|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.

|:h id=links:|=== 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.

|:table standard:|
``|:th width:20%:||=Format Name 
``|:th width:20%:||=Format Structure 
``|=Notes |
|Network Protocol Format|//protocol//:/~///address//| standard url format: http, https, ftp, nntp, news, mailto, telnet, file, irc|
|Symbolic Link Format|//Symlink//:%s font-style:italic%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 [[Local:module|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.

|:h id=decorators:|=== 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:

|:table standard width:100%:||:td colspan=4 text-align:center:|
``|=SimpleWiki Inline Decorators|
|:tr background-color:LightGoldenRodYellow:|
``|=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:

|:table standard width:100%:||:td colspan=3 text-align:center:|
``|=SimpleWiki Block Decorators|
|:th width:10%:||=Selector
``|:th width:22%:||=Target object
``|:th width:68%:||=Example|
|:tr background-color:LightGoldenRodYellow:||:th colspan=3 text-align:center:|
``|=**Paragraph**|
|p|paragraph|~|:p font-weight:bold:~|...|
|:tr background-color:LightGoldenRodYellow:||:th colspan=3 text-align:center:|
``|=**Dividers**|
|h|heading|~|:h section-divider-high:~|===...|
|b|empty block (divider)%s footnote%The //b// decorator is for an empty block, and must be alone on a line. To create a div use ~|:p div:~| ("change paragraph into div") instead, or use the (:div...:) block declaration |~|:b spacer dots:~||
|:tr background-color:LightGoldenRodYellow:||:th colspan=3 text-align:center:|
``|=**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 ... :~|: ...|
|:tr background-color:LightGoldenRodYellow:||:th colspan=3 text-align:center:|
``|=**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//|
``
|:tr background-color:LightGoldenRodYellow:||:th colspan=3 text-align:center:|
``|=**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).

|:h id=declarations:|=== 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

}}}

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

See [[Local:extensions#tagdefs|Tag Def Extensions]] for ways of getting and setting the set of tags that your client software can control.
==== Block Tag Declarations ====

|:table standard float:right width:250px margin-left:3px:|
``|:tr background-color:LightGoldenRodYellow:|
``|:th colspan=3 center:|
``|=**block declarations**|
|=Markup Tag|=Meaning|=HTML Tag|
|:tr background-color:LightGoldenRodYellow:||:td colspan=3 center:|
``|=content blocks|
|div|generic division|div|
|blockquote|indented block of content|blockquote|
|:tr background-color:LightGoldenRodYellow:||:td colspan=3 center:|
``|=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|
|:tr background-color:LightGoldenRodYellow:||:td colspan=3 center:|
``|=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|
|:tr background-color:LightGoldenRodYellow:||:td colspan=3 center:|
``|=dlml (%l newwin%[[http://dlml.org|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

|:p nop:|{{{<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.

|:b divider:|

|:table standard width:100%:|
``|:tr background-color:LightGoldenRodYellow:|
``|:th colspan=4 center:|
``|=** more block declarations**|
|=Markup Tag = HTML Tag|=Meaning|=Markup Tag = HTML Tag|=Meaning|
|:tr background-color:LightGoldenRodYellow:|
``|:th colspan=2 center width:50%:||=HTML 5 semantic tags|:th colspan=2 center border-left:"1px solid silver":||=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|:th colspan=2 center background-color:LightGoldenRodYellow:||=form tags|
|section|document section|form||
|header|page header|output||
|hgroup|header group|datalist||
|nav|navigation section|:th colspan=2 center background-color:LightGoldenRodYellow:||=muster widget tags|
|main|main content|:th colspan=2 center:||//reserved|
|details|a disclosure widget|mw-module||
|dialog|popup dialog|mw-widget||
|summary|summary of details|mw-settings||
|:th colspan=2 center background-color:LightGoldenRodYellow:||=HTML 5 ruby tags|mw-marker||
|ruby|ruby annotation (East Indian languages)|:td colspan=2 center:||//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
}}}
|:b spacer:|
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.

|:table standard width:100%:|
``|:tr background-color:LightGoldenRodYellow:|
``|:th colspan=4 center:|
``|=** inline tag declarations**|
|=Markup Tag = HTML Tag|=Meaning|=Markup Tag = HTML Tag|=Meaning|
|:tr background-color:LightGoldenRodYellow:|
``|:th colspan=2 center width:50%:||=appearance|:th colspan=2 center border-left:"1px solid silver":||=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|
|:th colspan=2 center background-color:LightGoldenRodYellow:||=phrase elements|:th colspan=2 center background-color:LightGoldenRodYellow border-left:"1px solid silver":||=form|
|code||select||
|dfn|definition|option|//for select|
|em|emphasis|label||
|strong||textarea||
|kbd|keyboard|:th colspan=2 center background-color:LightGoldenRodYellow:||=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:)
}}}
|:b spacer:|

|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%
}}}
|:b spacer:|

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

|:h id=arguments:|=== 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:

|:table standard width:100%:||:tr background-color:LightGoldenRodYellow:|
``|:th width:15%:||=Argument
``|:th width:15%:||=Format
``|=Description ```leaves width:55%
``|:th width:15%:||=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.

|:h id=macros:|=== 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 [[Local:module|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").