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 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 an indented verbatim block which continues until the next non-blank line which is not indented (or to the end of input/file). Contents of indented blocks can be styled as need be; for example, an alternative form of verbatim blocks.
This is a normal paragraph.
This is a indented 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 size of the white space block in output is proportional to the number of input lines;
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]
The above will be linked if a definition with the same key appears in the input, either before or after the reference. 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/
To reduce repetition, links local to the same document (e.g. fragments, in HTML) are inferred from the display text (possibly filtered/translated depending on the output format).
If the link parentheses contain a single # (octothorp), the display text is used to infer a local ID. The two following links are semantically equivalent.
[Epistemology](#)
[Epistemology](#Epistemology)
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 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 (text, switch, menu, file) are used to get user input.
Each input element associates a value to a name. The name can be specified explicitly by attribute; otherwise, it is inferred. The same is true for value in the case of switch sets (check boxes, radio buttons).
Inline text inputs specify contents (at least one character) enclosed in square brackets like links but the brackets are padded with one _ (underscore). The following example displays an input with "contents" already present and ready to be edited.
[_contents_]
Empty inputs are specified with contents of underscores only.
[____________]
Extra underscores at the beginning or end of non-empty contents are not printed but they inform the alignment and size of the displayed input, which is proportional to the length of contents.
[_____right alignment_]
Use escapes to include a literal underscore at the beginning or end.
[_\_literal_]
Text entry can be obscured (e.g. password inputs) with the class obscured.
password: [__________]{.obscured}
The syntax for block text inputs is identical to block containers, except the line character is limited to < (less than).
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
This text will be displayed in the input
as default text ready to be edited.
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<{#id}<<<
The size of the displayed input is proportional to the number of lines enclosed (including blank lines).
Switches are of two types: regular (toggles, check boxes), exclusive (radio buttons).
Regular switches meet the needs of binary toggles and ternary check boxes (differentiated by context/attribution). The syntax for regular switches is the same as text inputs, except there are no underscores and they contain only one character (which indicates state).
[ ] just an unset switch
Binary switches (toggles) have two possible states: true, false, specified by x " " (x, space) respectively.
[x] true
[ ] false
Ternary switches (check boxes) have three possible states: true, false, indeterminate, specified by x " " - (x, space, hyphen) respectively.
[x] true
[ ] false
[-] indeterminate
A set of regular switches can be used to associate multiple values to a shared name. Assuming the name "fauna", the following example produces an array for "fauna" (in addition to the basic Boolean value for each individual switch).
[x] raven
[ ] snake
[x] frog
fauna=[raven, frog]
raven=1
snake=0
frog=1
An exclusive switch refers to a set of values associated to a shared name which ensures assignment of exactly one value (instead of zero or more values as for a similar set of regular switches).
The syntax for exclusive switches is the same as regular switches but with parentheses instead of square brackets (and without syntax for indeterminacy as that is implicit if all members are empty).
( ) small
(x) medium
( ) large
Menus can be specified by reference to a list element (implicit, regular, ordinal) enclosed in square brackets.
here is a [menu]
[menu]: item one
item two
item three
Menus can also be specified inline following the same form as links: menu title enclosed in square brackets immediately followed by a list of items enclosed in parentheses.
[menu title]( one two three another )
[menu title](,one,two,this one has spaces,)
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 items (unless the item is quoted or the character is escaped).
Nested submenus are inferred by reference to a nested list, or inline by specifying a menu element as a menu item.
[menu]( m1 m2 [submenu]( a b ) m3 )
Items enclosed in * (asterisk) are displayed already selected.
[pre-selection]( a b *c* d )
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).
[<...]
Attributes for name and value are inferred if not explicitly specified.
The name attribute is inferred with the following precedence.
id attributeid attributeValues are only inferred for switch sets (as all other input elements yield explicit values), and only from adjacent text.
Text input name from adjacent text:
name: [_______] -> name=""
Text input name from default value:
[_name____] -> name=""
Menu name from adjacent text:
size: [](:S:*M*:L:) -> size=M
Name from parent id, value from adjacent text:
(x) forward
( ) back
{#go} -> go=forward
[x] Fuji
[x] Ambrosia
[ ] Cameo
{#apples} -> apples=[Fuji, Ambrosia]
Special syntax to isolate a segment of adjacent text (produces the same output as above):
[x]<-[Fuji] (I used to prefer these)
[x]<-[Ambrosia] (these are better)
[ ]<-[Cameo] (sometimes too acidic)
{#apples} -> apples=[Fuji, Ambrosia]
Name and value from adjacent text:
size: ( ) small, (x) medium, ( ) large -> name=medium
trees: [ ] yew, [x] cedar, [x] fir -> trees=[cedar, fir]
Several elements make use of references, as described above. References can be used to simplify/clarify the text by substituting concise place holders for inline syntax which 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, menus)
If the definition contains multiple lines, all lines following the first line are prefixed with one level of indention (which is removed from output). Menus accept lists only (inline or block).
[key]: URL (links, substitution)
Relative URLs which do not begin with / or ./ or ../ or ? or # are delimited (e.g. <url>) to disambiguate 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 enclosed in braces (to disambiguate from text substitution). A definition containing only one reference is an attribute reference (not a text substitution reference).
[key]: (uninterpreted literal string)
Abbreviation contents are enclosed in parentheses.
Although definitions have five distinct name spaces as described above, the name spaces of their references is more complex
References for substitution address three name spaces: text, URL, command.
An attribute group which contains a single reference is identical to substitution reference; hence, some cases remain unresolved by context alone.
Although the definition name spaces for links, triggers and menus are distinct, they all share the same reference name space as their reference syntax is identical.
These ambiguities are resolved by giving precedence to the first match scanning forward from a given reference to the end of input, then scanning backward from the reference to the beginning of input.
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 : descriptionnull : prefix section numbers to headings if non-null, beginning section numbers at given 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 (minimum: 2 enables block elements to be disambiguated by an extra blank line)empty : additional line characters to extend the default set
Options can be specified by the following methods and precedence: