A simple/unobtrusive/versatile formal language to structure plain text for logical manipulation.
This document is a detailed reference. See also:
Input text is interpreted to expose a structure of elements which can be processed as need be and translated to various output formats.
Elements are divided into two primary classes:
Elements are identified by bounding markers, inferred from ordinary punctuation when possible (e.g. a blank line separates paragraphs). Additional syntax is intended to be typographically cogent/coherent.
The syntax/grammar is specified formally for the parser [not finished], and described in detail for human readers below. Some terms to be clear:
Block elements are delimited by one or more blank lines or beginning/end of input.
A paragraph is one or more contiguous lines of text. Individual lines can be indented, but at least one line must be without indent (because if the whole paragraph is indented, it is a verbatim block, not a paragraph).
Line breaks are respected.
Headings are specified with character lines, i.e. a line of three or more contiguous and identical line characters: # * = - : (octothorp, asterisk, equal, hyphen, colon). Line characters cannot be mixed for a given heading. The characters listed above are always available, but the set can be extended by setting the [line-chars](#) option.
An underlined heading is one or more contiguous lines of text immediately followed by a character line.
Being There
---------------------
Headings can also be overlined. The length of lines need not match each other, nor the length of the heading text.
=========
Beware of Dogma
=============
Lined (i.e. underlined and overlined) headings can include line breaks.
Dr. Strangelove
or: How I Learned to Stop Worrying and Love the Bomb
*******************************************
A single-line heading is recognised for a single line of text beginning and/or ending with a character line.
### Harold & Maude
Kurt Schwitters :::::::::::::::::::::::
====== The double-slit experiment ======
More or fewer line characters can be used to adjust visibility in the source text without semantic effect. The line characters are separated from the heading text by inline white space.
For each of the three categories (overline, underline, single-line), each type of line character represents one style; i.e. multiple headings which use the same line character differ in style only if they also differ in category.
With the default set of five line characters, 15 heading styles are available, giving depth to rank and a wide range of choice to suit various texts.
In similarity to reStructuredText, the order of rank (or level) of a given heading style is defined by the order of occurrence.
Starting at the beginning of the document, each new heading style is assigned the next lower rank; i.e. rank corresponds with the order of first appearance of each style in the document.
This implies consistent usage and the potential to cause conflicts by following a given heading style with one already assigned that is subordinate by more than one level. In conflicting cases, rank is simply reassigned ensuring hierarchical structure and coherent ranking. Rank is automatic and cannot be specified.
A given heading also implies and produces a section container element which includes the heading and the associated list of following elements until the next heading of equal or greater rank, or to end of input.
ISO 2145 section numbers (e.g. 2.7.1) can be optionally prefixed to all headings. The section number is inferred (like rank, as described above). Section numbers begin at one by default but the starting point can be optionally specified.
Sometimes, it is preferable to minimise white space in the source text; therefore, the usual trailing block boundary is relaxed for headings; i.e. the blank line(s) separating a heading from the following element can be omitted.
=== Compact ========
No harm done.
A list is a series of list items of a common type. List items are of four types: implicit, regular, ordinal, associative.
Paragraphs are lists of lines.
Regular list items begin with a marker: - * + . (hyphen, asterisk, plus, period) followed by inline white space. (UTF-8 syntax... The following UTF-8 characters are recognised as markers: · • (middle dot, bullet).)
- sunflower seeds
- hibiscus petals
- dandelion stalks
List items can contain block elements. Contained blocks are indented one level from parent.
- hemlock
- red cedar
A paragraph (child of "red cedar").
The usual block boundaries are modified within lists:
Ordinal list items follow the same rules as regular list items, except the marker is different. The marker is an ordinal symbol (integer, letter, Roman numeral) followed by a period or right parenthesis (optionally fully enclosed with a left parenthesis), and inline white space.
1. breathe
2. drink
(a) water
(b) beer
3. sleep
Ordinal list items can also be marked implicitly. An octothorp # indicates integer values; #a or #A indicates letters (lower- or upper-case); #i or #I indicates roman numerals (lower- or upper-case).
#. integers
#a. letters
#i. roman numerals
Associative list items contain terms and associated descriptions.
In compact form, each item is a single line containing a single term/description pair. The term is followed by a colon and one tab width of inline white space (to disambiguate from paragraphs containing colons). Like the other lists, a single blank line separating items is optional.
term: description
musician: Albert Ayler
lachrymal: associated with weeping or tears
Descriptions can contain block elements (indented one level), though terms cannot. Descriptions containing block elements are located, with colon (to distinguish multiple terms), on the line below the term (and separated from the term by inline white space of one tab width or less).
term
: description
religion
: Ambrose Bierce writes:
"A daughter of Hope and Fear explaining to Ignorance,
the nature of the Unknowable."
Items can contain multiple terms and multiple descriptions. Within each item, all terms are associated with all descriptions.
stool
chair
: an item of furniture
: a platform for a hind form
Adjacent lists are separated by two or more blank lines.
Spacing of lists can be adjusted to achieve three forms:
blank line before list, blank line between items
Preceding block.
- expanded
- maximum space
blank line before list, contiguous items
Preceding block.
- compact
- remains separated from the preceding block
list contiguous with preceding block, contiguous items
Preceding block.
- compact/contiguous
- minimum space
If a paragraph is indented, it marks a verbatim block which continues until the next non-blank line which is not indented (or the end of input/file). Contents of verbatim blocks are treated literally; i.e. their contents are not parsed.
This is a normal paragraph.
This is a verbatim block.
A verbatim block can also be produced by enclosing text in lines of contiguous ` (backtick) characters. In this case, indentation is not required; any indentation will be output in the verbatim block contents.
``````````````````````````````````
if(rp->p_flag&SSWAP) {
rp->p_flag =& ~SSWAP;
aretu(u.u_ssav);
}
``````````````````````````````````
Lines of backticks can be included in a verbatim block if they are shorter than the containing lines.
Quotation blocks are containers which indicate that their contents are a quoted excerpt from another source. Quotation blocks use e-mail quoting: lines prefixed with one or more > (greater than). Quotation blocks can contain other block elements.
> Theodor (Dr.) Seuss Geisel
> ============================
>
> "Be who you are and say what you feel,
> because those who mind don't matter
> and those who matter don't mind."
Nested quotation blocks are like those of e-mail. In the following example, the first line is nested one level.
>> I just discovered György Ligeti!
>
> Great! Did you hear his first string quartet?
Blank lines separating block elements need not be prefixed. Only the first line of a block need be prefixed.
>> Albert Hofmann wrote this:
>> I share the belief of many of my contemporaries
>> that the spiritual crisis pervading all spheres of
>> Western industrial society can be remedied only by
>> a change in our world view. We shall have to shift
>> from the materialistic, dualistic belief that
>> people and their environment are separate, toward a
>> new consciousness of an all-encompassing reality,
>> which embraces the experiencing ego, a reality in
>> which people feel their oneness with animate nature
>> and all of creation."
> flowers for Albert! :}
A quotation block is also produced for a series (one or more) of quoted paragraphs (i.e. each paragraph enclosed in quotation marks). An optional attribution (author/source/&c.) can follow the closing quotation marker, separated by white space (not more than one blank line).
An inline attribution is inline text beginning with -- (two hyphens), separated from the quotation by inline white space.
"We act as though comfort and luxury were the chief requirements of life, when all that we need to make us happy is something to be enthusiastic about." --Albert Einstein
A block attribution is a paragraph or list, indented and separated by one blank line.
"The fact that certain bodies, after being rubbed, appear to attract other bodies, was known to the ancients."
author: James Clerk Maxwell
text: *Treatise on Electricity and Magnetism*
via: Bret Victor
A block separator (used to emphasise separation of adjacent blocks) is a line of three or more identical line characters # * = - : (the same as those used for headings), optionally separated by inline white space (one tab width or less) at any position.
----------------------
* ** * ** *
White space blocks provide variable-size white space separation between blocks. Contiguous blank lines are respected as a white space block if the number of lines is above threshold.
A threshold is used because white space can be useful in making the source text easier to read without affecting output. The default output threshold of four (which can be adjusted by setting the options) leaves a variable margin of one to four lines available for block boundaries.
The number of output lines (i.e. the size of the white space block) is equal to the number of input lines minus the threshold value; e.g. between two block elements, five or more blank lines are needed to affect output (assuming threshold of four).
Simple tables of two or more columns are recognised. For each row, adjacent values (i.e. columns) are separated by inline white space (one tab width or more). Empty values are represented as an empty quoted string: "" or ''.
Name Life Region
-----------------+ -----+----- +---------
Perotin fl. c. 1200 France
Couperin, François 1668 - 1733 France
Ligeti, György 1923 - 2006 Romania
"Three noteworthy composers."
Both column headings and row headings are optional.
If column headings are present, they are separated from table data by the alignment line (described below).
If row headings are present, they are separated from table data by one space followed by a single | (vertical bar, pipe).
This method of alignment (in combination with variable padding between values, and syntax for empty values) enables independence from character columns (i.e. fixed-width fonts).
The alignment line is not optional. Alignment is inferred from a line of hyphens broken into segments: one segment for each column. A single space is sufficient to separate segments (i.e. any additional inline white space is semantically equivalent). Each segment contains at least two hyphens. Each segment can use alignment characters to specify five types of alignment.
left right mid string justify
+----- -----+ ---+--- ---.-- +-----+
Several alignment marker characters are available: + = ^ (plus, equal, caret) which can be used to specify alignment as shown in the example above.
The alignment markers for both mid and string alignment can appear at any position in the hyphen line, if at least one hyphen is present on each side; i.e. they need not be balanced.
String alignment aligns on a string (of one or more characters) found embedded in a segment (assuming the output format supports this kind of alignment). The string can be quoted and escaped as need be.
--' - '-- -----:------ ---.--
Alternatively, alignment markers can be omitted for left, right, and mid alignment, which is then inferred from the number of characters in each segment: even numbers are left, odd numbers are right, except multiples of three are mid.
right mid left
----------- ------------ ----------
odd 3n even
If a quoted paragraph follows the table data, separated from it by one blank line, it is used as a caption. (A quoted paragraph form of quotation block, which follows a table having no caption, is separated by two or more blank lines; otherwise, it's a caption.)
Inline elements contain one or more characters except line breaks. All text is recognised as a series of inline elements (contained in zero or more blocks). Contiguous inline text is recognised as a raw/default inline element if recognition by all other inline elements fails.
Emphasis only works if the markers are adjacent to the enclosed text (not separated by white space).
Text can be emphasised by enclosing it in a matched pair of * or ** (single- or double-asterisk) markers, for normal (italic) and strong (bold) emphasis, respectively.
If your life isn't interesting, you're *not* paying **attention**!
Text can be de-emphasised by enclosing it in a matched pair of ~ or ~~ (single- or double-tilde) markers, for normal (weak; i.e. reduced contrast) and strong de-emphasis (e.g. struck), respectively.
The Origins of Order ~(ISBN: 0-19-505811-9)~
strong de-emphasis ~~intellectual property~~
The following are recognised as hyperlinks:
http://www.edge.org/
edwardburtynsky.com/projects/films
pleonexia@apple.com
Automatic links are only recognised if they are separated from adjacent text by white space, or by characters which are not contained in URLs.
Links can also be delimited with < and > (less-than and greater-than), markers which permits any adjacent character (the markers are removed from output).
<http://www.edge.org/>
<edwardburtynsky.com/projects/films>
<pleonexia@apple.com>
Links can display text instead of their URLs.
[this text is displayed](http://www.eff.org/)
[local resource](./ecology)
To make the source text easier to read/edit, the display part can be separated from its URL using a reference key and associated definition.
[useful software][key]
This only works if a definition with the same key also appears somewhere in the document. More on references...
[key]: http://www.roaringpenguin.com/remind
Alternatively, the reference key can be omitted, causing the display text to be used as the definition key.
Do you know about [Plan 9]?
[Plan 9]: https://p9f.org/
Links within the same document/page (e.g. fragments, in HTML) are inferred from empty parentheses. The display text is used with characters removed/replaced as defined by the output filter. The two following links are semantically equivalent (assuming character conversion for HTML output).
[Anima Mundi]()
[Anima Mundi](#anima-mundi)
Triggers are essentially links (or buttons) for commands (instead of URLs) which are triggered/evaluated when the links are followed.
Syntax is identical to that of links except that the URL is replaced by a command, a string beginning with % (percent) followed by a single space.
[link text](% command)
In reference form they are identical to links but the definition is distinguished by command syntax.
[link text][key]
[key]: % command
Implicit reference.
[link text]
[link text]: % command
Triggers can be used to toggle the display/visibility of elements (such as in situ notes/help), and a shorthand syntax is provided.
Clean the heads. [Note...]?{#head-cleaner}
The following trigger would produce the same result (assuming functional equivalence).
Clean the heads. [Note...](% toggle '#head-cleaner')
Target elements can be specified using an attribute pattern: All elements which match the attributes in the pattern are target elements. The attribute pattern has the same form as an attribute group.
Help and notes, [show/hide...]?{.help .note}
Help and notes, [show/hide...]?{t}
[t]: {.help .note}
If the element to be toggled is inline, and immediately follows the trigger, it can be specified in the trigger. The parenthetic part is replaced with square brackets containing the text to be toggled.
The typewriter is dead[...]?[ and haunting us in so many ways.]
Substitution is used to include the contents of other resources (such as images).
Several types of substitution are available:
Substitution elements are enclosed in braces and return either block or inline contents.
Text substitution uses placeholder references, which specify location, keyed to units of arbitrary text defined to replace them.
{key}
[key]: this text replaces all instances of {key}
Substituted text is parsed with the whole document; effectively, substitution occurs before the document is parsed. The key is enclosed in braces. The definition can contain block elements. More on references...
URL substitution is used to include images or other resources (i.e. whatever is retrieved from the given URL). To disambiguate from text substitution, relative URLs begin with / or ./ or ../ or ? or #.
{/image.jpg}
Like links, URL substitution elements can be specified by keyed reference to a definition.
{key}
[key]: /image.jpg
The results of shell commands can be substituted, to include objects and meta-elements generated at output time (e.g. table of contents, excerpts from other files, &c.).
Commands begin with % (percent) followed by a single space.
{% command}
Alternatively, the command can be assigned by reference.
{now}
[now]: % date '+%x'
Text enclosed in ` (graves/backticks) is a verbatim string. Contents of verbatim strings are treated literally; characters are deprived of any special meaning.
`*this* is not an emphasis element`
A matched pair of multiple markers can be used to enclose a verbatim string that includes backticks.
``a tick ` is in here``
```five ticks ` are `` in `` here```
The markers can be padded with a space to permit a backtick at the beginning/end of the string.
`` `date` ``
Multiple contiguous backticks can be enclosed with single, space-padded backticks.
` backtick tock ````` `
Text enclosed in matched quotation marks is recognised as an inline quotation. Supported quotation marks:
Notes associate a specified locations in the text with supplemental text to be specially displayed (as foot notes, side notes, &c.).
Notes can be specified with references. The reference is replaced with a reference symbol cross-linked to the definition (if a definition is found for that reference).
A definition key for note elements is a text string enclosed in square brackets, prefixed with * (asterisk). Because the key text is also used as an ID attribute (for cross-linking), its characters/format may be restricted by a given output format.
One can use notes.*[key]
The associated definition begins with the key followed by a colon, and the note contents. Note definitions can contain indented block elements.
[key]: Notes need not be footnotes; side notes may be preferable.
Linked reference symbols are automatically generated and appear in the output as superscript integers1 (1, 2, 3, ...); or, if there are three notes or less, as conventional typographic references*†‡ (asterisk, dagger, double dagger).
References can be associated by linking part of the text as an implicit key, appearing as a normal text link (not superscript). In this example, the word paper is a link, cross-linked to the definition.
There is no [paper]* here.
[paper]: Though the pernicious paper paradigm persists.
These text link references can also be specified with explicit keys.
Yes, another [pernicious paradigm]*[p]...
[p]: ...so subliminal and orthogonal in its invisible influence.
If a note contains no block elements, it can be defined inline (without a key).
Nusrat Fateh Ali Khan*[Certainly not a terrorist.]
Inline notes can also be specified as text links.
Captain [Beefheart]*[because he had a beef in his heart]
Abbreviations can be defined for a given string by placing a definition somewhere in the document. Abbreviation definition keys are enclosed in square brackets. The definition contains a literal (uninterpreted) string of text (no line breaks) enclosed in parentheses.
The following example associates the text «Signal to Noise Ratio» with all instances of «SNR» (which are surrounded by white space or punctuation/boundary characters). More on references...
[SNR]: (Signal to Noise Ratio)
Inline lists are recognised within sentences. Inline text followed by a colon, space, two or more delimited items of inline text, terminated by a . (period) or end of inline text.
Survival skills: empathy, humility, gratitude.
List items in a given list are delimited by either , (comma) followed by a space or ; (semicolon) followed by a space (i.e. mixed delimiters are not recognised). The list elements do not include syntactic punctuation (colon, list delimiters, terminal period).
Containers are primitive elements which greatly extend semantic possibility with minimal syntax. They can be used for arbitrary content which is not addressed by the other elements; indeed, the syntax for all other elements is essentially shorthand as it is possible to specify any element using only containers and attributes.
Container elements are always specified with an attribute group.
Block containers contain zero or more block elements. Block containers are marked by lines of three or more identical line characters # * = - : (the same as those used for headings and block separators):
-------------------------------------
block content
-----------------------------{#id}---
The attribute group is embedded in the closing line, at any position, at least three characters from each end.
Block containers take precedence over block separators; i.e. a block container cannot contain a block separator which uses the same line character.
An inline container is a string of inline text enclosed in square brackets followed by an attribute group.
enclosure of [an arbitrary phrase]{a}
or em[bed]{b}ded within a word
Attributes are used to associate semantic information with elements, though the actual meaning of attribute values remains dependent upon the output context. There are four types:
#id.classname="value"keyValues assigned to these types are expected to respect restrictions of the output context.
In name/value pairs: the value can be unquoted if it contains no white space; otherwise, (single or double) quotes are used. Identical quotes and backslashes are escaped/prefixed with \ (backslash).
Any attributes (values of the above types) associated with a given element, are are enclosed in braces and assigned to the element as a unit group. An attribute group contains one or more items (separated by a single space).
{#id .class name="value" key}
The reference type (similar to that of reference links, abbreviations, &c.) permits the separation of long assignments from their target elements in the source text. A given key is included in one or more attribute groups and defined elsewhere in the document.
{#borealis g}
An attribute reference definition contains one or more attribute assignments (including references). The key is enclosed in braces.
[g]: {genus=Phidippus family=Salticidae}
Definition contents are substituted for all instances of its key within attribute groups; effectively, the keys are expanded. The example above, {#borealis g}, is shown below with the definition expanded.
{#borealis genus=Phidippus family=Salticidae}
For inline elements, the attribute group is located immediately following (contiguous to) the element. The following example assigns the ID ken to a link, and assigns the class regex to an inline verbatim element.
[He](http://www.cs.bell-labs.com/who/ken/){#ken} gave us `reg(ex(ps|es|en)|ular expressions)`{.regex}, and so much more...
For block elements, the attribute group is located after the element, on its own line, optionally separated by one blank line.
Theodore Sturgeon wrote some interesting stories.
{.statement}
Ask the next question.
{q="next"}
For some elements, the line break is optional, as described below; however, in the block context, the attribute group is always separated from the contents by white space (to eliminate ambiguity).
For paragraphs, the attribute group need not be separated by a line break (if it is separated with inline white space).
So many good ideas are never heard from again once
they embark in a voyage on the semantic gulf. {s}
[s]: {source="Alan J. Perlis"}
As with paragraphs, the line break is optional.
James Clerk Maxwell
---------------------------------- {.physicist}
=== Andy Goldsworthy ====== {.artist}
Element identifiers can also be specified implicitly with a singular # (octothorp): the heading text is used as the identifier (filtered/translated to respect limits of the output format). The following example produces the ID automatic-link-targets for HTML output.
Automatic Link Targets
---------------------------- {# .class}
For list items with only inline contents, the line break is optional.
- Nuclear Rabbit {.music}
This includes description list terms, and descriptions with only inline contents. Attribute groups appearing after a description, are applied to the unit item (which includes term and description).
PEG {.term}: Parsing Expression Grammar {.item}
Packrat Parsing & PEG Resources {.term}
: http://pdos.csail.mit.edu/~baford/packrat/ {.item}
To eliminate ambiguity, the attribute group for the description is located between colon and contents (separated by inline white space).
Lisp {.term}
: {.description} An abstraction worth learning. {.item}
{.list}
An attribute group appended to a list item which contains block elements will be assigned to the last block element, unless it appears on a separate line, at the same level of indentation as the list item marker.
1. Fast, Cheap & Out of Control
============================ {.title}
A documentary film by Errol Morris, about a lion
trainer, a topiary sculptor, a mole rat specialist,
and a robot scientist.
{.blurb}
{.movie}
An attribute group line appended to a list is attached to the list, not the item.
- *Ender's Game* by Orson Scott Card
- *The Diamond Age* by Neal Stephenson
{.list}
If two attribute group lines are present, the first is attached to the last item, and the second is attached to the list.
- *Joseph Spence - The Complete Folkways Recordings, 1958*
- *The Country Blues of John Lee Hooker*
{.item}
{.list}
For the block elements enclosed in character lines (verbatim blocks, block containers), the attribute group is embedded in the last character line, to disambiguate from overlined headings. The attribute group is located at any position in the character line, separated from both ends by at least three line characters.
====================================
This is a container, not a heading.
====================={.container}===
In the case of collisions (multiple assignments to the same name), the last assignment has precedence; any previous assignments to the same name are ignored. To make this work with references, all reference identifiers are effectively moved to the beginning of the attribute group (ordered as found) before expansion.
[r]: {a=1}
[s]: {b=3}
{s b=8 r} → {s r b=8} → {b=3 a=1 b=8} → {a=1 b=8}
Input elements can be used to get user input. There are five types of input elements: text, check box, radio button, menu, file).
Each input element associates a value with a name. The name can be specified explicitly as a name attribute; otherwise, it is inferred. The same is true for value in the case of flags (check boxes, radio buttons).
Inputs with class hidden are not displayed.
Inline text inputs are specified explicitly by enclosing one or more _ (underscore) in square brackets, followed by <- (less-than hyphen), and an attribute group containing an ID (or a name attribute).
[_____]<-{#id name=Archaea}
If a name attribute exists (as above), it is used; otherwise, the ID is used as the name.
[_____]<-{#name}
Text can be displayed in the input by enclosing it in one or more _ (underscore) to disambiguate from check boxes.
[_default value_]<-{#name}
The size of the rendered input is proportional to the number of characters enclosed between the square brackets.
Text entry can be obscured (e.g. password inputs) with the class obscured.
password: [__________]<-{#name .obscured}
A block text input is identical to a block container, except the attribute group is preceded by <- (less-than hyphen), and contains an ID or a name attribute (following the same rules for name precedence as inline text inputs).
=============================
This text will be displayed in the input
as "default" text which may be replaced.
==================== <-{#name} ===
The size of the rendered input is proportional to the number of lines enclosed (including blank lines).
Flags are essentially binary switches (i.e. they are either on or off). There are two types of flags: check boxes, radio buttons.
The syntax for check boxes is the same as text inputs, except there are no underscores and they contain only one character (which indicates state).
[ ]<-{#name}
Sometimes the state of a flag is indeterminate; therefore, there are actually three possible states: true, false, indeterminate. The state is specified with x - (x, space, hyphen) for true, false, indeterminate, respectively.
[x]<-{#a} (true)
[ ]<-{#b} (false)
[-]<-{#c} (indeterminate)
When attributed to a common name, multiple check boxes can be used to assign zero or more values to that name.
[ ]<-{name=a value=x}
[x]<-{name=a value=y}
[x]<-{name=a value=z}
Because they share a common name, the name is specified explicitly, not inferred from the ID; however, if values are not specified explicitly, they are inferred from the IDs.
[ ]<-{#x name=a}
[x]<-{#y name=a}
[x]<-{#z name=a}
A check box without a value associates a boolean value (true or false) to its name.
Radio buttons are like a multi-value check boxes but specialised to select exactly one value from a set of values associated to a common name; accordingly, radio buttons always have specific values. The following example also illustrates attribute references.
( )<-{a}
( )<-{b}
(x)<-{c}
[a]: {value=papaya n}
[b]: {value=mango n}
[c]: {value=coconut n}
[n]: {name=eat}
For each radio button, the name is either specified explicitly in the attributes (which enables individual buttons to be in different locations), or it is inferred from the containing element (e.g. apple=Ambrosia).
(x)<-{value=Ambrosia}
( )<-{value=Fuji}
{#apple}
Indeterminate radio buttons have no special syntax because a given group of radio buttons is implicitly indeterminate if none are selected.
Menus are a list of items enclosed in square brackets. Each menu item is a string delimited (much like sed) by a shared delimiter character (a space or any punctuation character) which is not contained in any of the strings (unless the string is quoted or the character is escaped).
[ one two three another ]<-{#name1}
[|one|two|this one has spaces|]<-{#name2}
Menus can be specified by reference to a list element (one of implicit, regular, ordinal).
here is a {menu}
[menu]: item one
item two
item three
Nested submenus can be created by reference to a nested list, or inline by appending a menu element to a menu item. The item text then becomes the title of the submenu.
[,m1,m2 submenu [ a b ],m3,]<-{#name}
Selected items are enclosed in * (asterisk).
[:a:b:*c*:d:]<-{#name}
Normally, only one item can be selected from a menu, but multiple selections can be enabled by replacing the - (hyphen) with = (equal).
[ a b c d ]<={#name}
Multi-selection menus can also be specified with multiple items selected by default.
[ *a* b *c* d ]<={#name}
File inputs are used to input the contents of a file. The syntax is identical to an inline text input, except the square brackets contain only <... (less-than period period period).
[<...]<-{#name}
[I'm still refining the form of input elements – mostly the short-form syntax and rules of inference, rather than the explicit syntax – so this section is somewhat unstable.]
The value can be explicitly borrowed from adjacent text (which will be rendered) by enclosing it in square brackets.
apples=[Fuji, Ambrosia]
[x]<-[Fuji] (I used to prefer these)
[x]<-[Ambrosia] (these are better)
[ ]<-[Cameo] (sometimes too acidic)
{#apples}
size=large
fabric=[breathable, stretch]
size: ( )<-[small], ( )<-[medium], (x)<-[large]
fabric: [ ]<-[waterproof], [x]<-[breathable], [x]<-[stretch]
Value inferred from adjacent element. Name inferred from containing element (e.g. apple=Ambrosia).
( ) Fuji
(x) Ambrosia
( ) Cameo
{#apple}
apples=[Fuji, Ambrosia]
[x] Fuji
[x] Ambrosia
[ ] Cameo
{#apples}
Several elements make use of references, as described above. Although inline syntax is available, references can be used to simplify/clarify the text by substituting concise place holders for what may be otherwise distracting in situ.
The following common rules apply:
All definitions share a common form: beginning on a new line, the key is enclosed in square brackets, followed by a colon and a single space, followed by the definition contents.
There are five types of content, hence five name spaces:
[key]: content (element context)[key]: inline or block (notes, substitution)
If the definition contains multiple lines, all lines following the first line are prefixed with one level of indention (which is removed from output). Text substitution can be nested but the definition must contain more than one reference (to disambiguate from attributes).
[key]: URL (links, substitution)
Relative URLs which do not begin with / or ./ or ../ or ? or # are delimited (e.g. <url>) to disambiguate them from text substitution.
[key]: % command (triggers, substitution)
Commands are prefixed with % (percent) and a single space.
[key]: {#ID .class name="value" key}
Attributes are given as an attribute group. Enclosing braces disambiguate the definition from text substitution. A definition containing only one reference is an attribute reference (not nested text substitution).
[key]: (uninterpreted literal string)
Abbreviation contents are enclosed in parentheses.
Some elements address multiple name spaces, merged with the following precedence:
link: URL, command
substitution: text, URL, command
Except inside verbatim elements (verbatim, verbatim blocks), any punctuation character can be escaped with a preceding \ (backslash); i.e. the backslash is omitted from output and any special meaning otherwise associated with the following character is ignored/escaped.
no \*emphasis* here
Verbatim elements (verbatim, verbatim blocks) can be escaped (of any verbatim formatting) by assigning the class: escape.
Connotext does not recognise other languages (HTML, TeX, &c.) but foreign code can be embedded/contained/attributed and passed through as raw/unmodified text (to be interpreted externally) by using verbatim elements (verbatim, verbatim blocks) with the class: raw.
Document metadata can be included at the head of the document. This metadata is a compact associative list in which each item is prefixed with % (percent).
% author: Edwin A. Abbott
% date: 1884
% title: Flatland
% arbitrary name: arbitrary value
The behaviour of a connotext parser can be adjusted by modifying the following options.
default : descriptionfalse : prefix section numbers to headings1 : begin section numbers at this valuefalse : infer ID for all headings (heading text with bad characters converted)4 : number of spaces equivalent to one tab (minimum: 2)4 : white space blocks are only recognised for quantities of contiguous blank lines greater than this integer; the number of output lines is equivalent to the number of input lines minus this threshold; it must be two or greater (because double blank lines are used to disambiguate contiguous lists, &c.)empty : additional line characters to extend the default set
Options can be specified by the following methods and precedence: