Semantic Authoring Markdown (SAM)

Declarations must come before all other content. A declaration is created by a line beginning with an exclamation mark followed by an declaration type followed by a colon.

!namespace: http://spfeopentoolkit.org/sam/ns/tests

The root had no syntax of its own. It is an implicit container for the contents of the file.

A block is indicated by a string consisting of:

• the appropriate indent for its position in the document structure

• the field name

• a colon

• attributes, if any

• at least one space

• the field value

• a line end

name: Fred Flintstone
address:(?foo) Bedrock
era: BC

The name of a field must be a valid SAM name.

The value of a field is a flow, meaning it can contain phrases, decorations, annotations, and citations.

A block is syntactically identical to a field. It is distinguished from a field based on whether or not it has children. The children of a block are any structures following the block header that are indented more than the block header.

The following example defines a block named movie-review. It is a block because it has children. Its children are the field movie and the block stars:

movie-review: Wayne shines in Rio Bravo
    movie: Rio Bravo
    stars:
        star: John Wayne

The movie-review block as a value, Wayne shines in Rio Bravo' which will be treated as the title of the block on serialization. The stars` block does not have a value. Its function is to act as a container for the list of stars. (As part of the regular structure of a movie review, the list of stars would likely be assigned a title during output processing, but it does not need one in the source.)

The document block is not indented. All other structures in the document (excluding comments, declarations, and string definitions) must be children of the document block, and therefore must be indented under it. In all other respects, the syntax of the document block is the syntax of it type.

A paragraph is indicated as sequence of lines ending with a blank line.

Now is the time
for all good men
to come to the aid
of the party.

It was the best of 
times, it was the 
worst of times.

Any line that is not identified as a different structure, or an attempt to create a different structure, is identified as a paragraph.

In some cases a paragraph may begin with a sequence that looks like an attempt to create a different structure. For instance, if there is a colon before the first space in a paragraph, and if the string before the colon is a name-like-value, then the writer can prevent the sequence being recognized as a block or field by escaping the colon with a backslash or a character escape.

Once the first line of a paragraph has been identified, the parser simply accumulates subsequent lines, without looking for other structures, until one of the following is encountered:

• A blank line.

• A line whose indent is less than the indent of the first line of the paragraph.

• If the paragraph is the child of a list item, the start of a new list item.

A paragraph cannot have block children. Is is an error if any structure is indented under a paragraph.

The content of a paragraph is a flow. A flow is distinct from a simple string value in that it can contain phrases, decorations, code, annotations, and citations.

There is no special syntax to define a flow. Flows are defined by their relationship to other structures. All flows are trimmed of leading and trailing whitespace. In composing a flow from multiple text lines, all spaces and returns are collapsed to a single space.

A phrase is indicated by surrounding the phrase with curly braces:

In {Rio Bravo}, {the Duke} plays a union colonel.

It is not an error to have a phrase with no attributes, annotations or citations attached. When such as phrase is found, the parser must:

• First, look backward through the document to find out if the same phrase has been annotated before. If it finds the same phrase, with an annotation, it copies the entire phrase and all attached annotations to the current phrase. The search proceeds in reverse document order and stops at the first instance found.

• Second, if no matching phrase is found, the parser must issue a warning for the unannotated phrase.

The search is conducted based on the annotation lookup mode in effect for the document, as determines by the annotation-lookup declaration.

Note that attributes, citations, and local annotations are not copied.

Attributes on blocks are contained in parentheses that follow the colon of a block header with no space:

name:(?BC) Fred Flintstone

A block can have multiple attributes, one after another, with no spaces between:

name:(?BC)(#fred) Fred Flintstone 

Attributes on phrases are contained in parentheses that follow the closing curly brace of the phrase or the closing parenthesis or bracket of another annotation, attribute, or citation.

An attribute annotation looks like this:

In Quebec, a stop sign says {Arrêt}(!fr).

A phrase can have an unlimited mix of attributes, annotations, and citations attached to it.

There are four general attributes. The type of an attribute it determined by the flag character that precedes it. The four general types are:

• Condition, which start with a ?

• Name, which start with #

• ID, which start with *

• Language code, which start with !

A block or phrase can only have one name, ID, or Language code attribute but it may have an umlimited number of condition attributes.

Condition expressions must not include commas.

Names must be SAM name tokens.

IDs must be SAM name tokens.

Languages should be BCP 47 language codes, but the parser is not required to enforce this.

Certain block types take additional attributes with meanings specific to those block types.

An annotation is attached to a phrase and is expressed as an expression in parentheses following the closing } of the phrase with no space in between.

An annotation specifies the type of a string. Here the type expression says that the string "Rio Bravo" is a reference to a movie:

In {Rio Bravo}(movie), {the Duke}(actor "John Wayne" (SAG)) plays a union colonel.

There are three parts to an annotation:

type

The first word immediately following the opening parentheses is the type of the subject being annotated. In the sample above, "Rio Bravo" is a movie and "the Duke" is an actor. An annotation type must be a valid SAM name. The annotation type is required.

specifically

In some cases, the annotated text may not specify its subject clearly. In this case, the specifically attribute is use to clarify what is meant. The specifically attribute is a string in double or single straight quotes. In the sample above, "the Duke" means, specifically, "John Wayne". The specifically attribute is optional.

namespace

In some cases, it is necessary to specify the namespace to which the annotated term belongs. The namespace attribute follows the specifically attribute (if specified) and is contained in parentheses. In the sample above, the name of the actor "John Wayne" is part of a set of names managed by the Screen Actors Guild which makes sure two actors don't use the same stage name. (In most cases, the namespace is implied by the type, so you will not usually need to specify it.) The namespace attribute is optional. (Note that the namespace attribute of an annotation is not related to the concept of the namespace of an block or field name. It is the namespace of the value, not the namespace of the container.)

If you are annotating the same phrase more than one in the same file. You can skip the annotation metadata and just use curly braces around the phrase. The parser will copy the metadata from the last occurring instance of that same phrase.

You can create a local annotation, one that applies to this instance of a phrase and will not be copied by the annotation lookup mechanism. To create a local annotation, precede the opening parentheses with a a +.

You can cancel a looked-up annotation (one that would normally be added by the annotation lookup feature). To cancel an annotation, create a cancel annotation, which consists of an annotation with an minus sign (-) before the opening parenthesis. The type name of the cancel annotation specifies the annotation type to be canceled. Cancel annotations cannot have specifically or namespace attributes. They cancel all instances of the canceled type.

A citation is created using square brackets:

Moby Dick[Melville, 1851] is about a big fish.

They can also be applied to a phrase, rather then floating in the text.

{Moby Dick}[Melville, 1851] is about a big fish.

Citations can be chained with annotations:

{Moby Dick}(novel)[Melville, 1851] is about a big fish.

Citations can also be added to blocks. The most obvious application of this is blockquotes:

"""[Melville, 1851] 
    Call me Ishmael.

SAM has no opinion about the format of a citation text. That is entirely up to the application layer to decipher.

You can use reference citations to reference other parts of the current document or other documents. To cite a resource that has an id within the current SAM document, reference the id like this:

Moby Dick is about a big fish[*fn.moby]. See [*fig.whale].

fig:(*whale)
    >>>(image whale.png)

footnote:(*moby)
    Actually, Moby Dick is a whale, not a fish.

Citation by id, name, or key can include additional information. For example, if you have a bibliography where each bibliography entry has a name assigned to it, you could cite the work by reference to the name, and then add additional information for the page number.

"""[#Moby page 1] 
    Call me Ishmael.

The additional information is anything between the end of the name and the closing square bracket.

Citations can also use compound identifiers. For instance, if you want to cite a figure in a chapter, you can cite it by an identifier that is composed of the chapter name and the figure id joined by a /:

See [#chapter.moby/*fig.whale]

At the block level, an insert is placed on a line by itself and is indicated by three greater-than signs:

>>>(image foo.png)

Inside a flow, an insert is indicated by a single greater-than followed the the identification of the resource in parentheses:

My favorite flavor of ice cream is >($favorite-flavor).

The resource to be inserted may be identified either by type and URL as in the block example above or by reference to an id, name, variable, or key.

You can also assign names, conditions, or ids to an insert. For example, to insert a fragment containing the introduction to the deluxe version of a product, you could do this:

>>>(~deluxe-intro)(?model=deluxe)

Remember that it is up to the application layer to implement such inserts.

You can use any name you like for the insert type, however the following types are reserved so that editors can act on them to provide enhanced views of the document while editing:

• image

• video

• audio

• feed

• app

• object

They should be used only with their natural semantics. Note, however, that the spec does not prescribe a mechanism for identifying the object to insert. The item will, of course, be identified by a URL, but how that URL is to be interpreted is not specified. For instance, it could point to an intermediate resource such as an XML file that contains information used to choose the appropriate object for a particular media. The SAM language spec does not specify the format or interpretation for such a file.

Inserts may also be specified by idref, nameref, or keyref:

>>>(#foo)

Inserts by reference can use compound identifiers:

>(#foo/*bar)

Insert syntax is also used insert the value of variables using a variableref:

>($boz)

A recordset consists of a set of records, one per line, with named fields. The recordset declaration consists of the record set name followed by two colons and then the names of the fields, separated by commas.

history:: date, author, status, notes

Each line indented below the record set declaration is a record, which contains field values separated by commas.

history:: date, author, status, notes
    2018-01-23, mbaker, draft, First draft
    2018-01-29, jsmith, draft, Added info on haggis
    2018-02-04, ajones, approved, Reviewed and approved with minor changes

Codeblocks begin with three back ticks followed by optional attributes.

```(python)
    print("Hello World.")

Code must be indented under the codeblock marker. The codeblock ends at the first line that is less indented than the codeblock marker, or at the end of the file.

Codeblocks take the standard attribute types.

Because is is delineated by indentation, the contents of a codeblock do not require any character escaping, and no SAM character escapes are recognized in a codeblock. The text is taken literally without modification of any kind.

Thus, for instance, you can show blocks of SAM in a SAM codeblock (as this document does) without any need for escaping any part of the markup.

An embed works just like a codeblock, except that there is an encoding attribute on the block.

```(=latexmathml)(*id13)(#name)(?a)(?b)
    n_{\mathrm{offset}} = \sum_{k=0}^{N-1} s_k n_k

A blockquote is created by and appropriate indent followed by three " or ' characters followed by optional attributes and/or a citation.

Mother Goose

The quick brown fox jumps over the lazy dog.

The contents of a blockquote is regular SAM markup, and thus can contain phrases and annotations.

To create a set of lines, precede each one with a pipe character followed by a space.

| You gotta walk that lonesome valley,
| You gotta walk it by yourself,
| Nobody here can walk it for you,
| You gotta walk it by yourself.

You can also add ids or conditions to lines. In this case, the opening parentheses of the annotation must follow the leading pipe character immediately, and the closing parenthesis must be followed by a space:

|(#foo2) You gotta walk that lonesome valley,[*bing page 22]
| You gotta walk it by yourself,
|(?bar) Nobody here can walk it for you,
|    You gotta walk it by yourself.

The entire line must be on one line in the source.

All spaces after the first space following the pipe are considered significant and are retained on output.

A line cannot have children.

The text of a line is a normal SAM flow and is processed as such.

An unordered list item is created by starting a paragraph with a * followed by a space. Note that the space is require. Without it, the * will be recognized as the beginning of a bold decoration, or as plain text.

* Dog
* Cat
* Monkey

The text following the * is treated as a paragraph. This means that the ordered list above is equivalent to this:

ul:
    li:
        Dog
    li: 
        Cat
    li:
        Monkey

and not this:

ul: 
    li: Dog 
    li: Cat 
    li: Monkey

The only way to get the latter structure is to enter it as shown above.

You can have more than one paragraph in a list item. To add a second paragraph, insert a space followed by a paragraph that is indented to the same level as the first letter following the * of the list item:

* How much is that doggy in the window.

  I hope that that fleabag's for sale. 

* Hey diddle diddle, the cat and the fiddle

  The cow jumped over the moon. 

List can be nested. A nested list means that one list is the child of a list item in the parent list. To create this, indent the second list under an item of the first.

* Dogs
    * Spot
    * Fang
* Cats
    * Mittens
    * Skimbleshanks

Note that when an unordered list follows a paragraph, it must be a the same indent level as the preceding paragraph, not indented under it.

The syntax of an ordered list is the same as for an unordered list except that it uses one or more numerical characters followed by a period followed by a space:

0. Robot
12. Spaceship
7. Ray gun

The numbers are not retained, nor is their style. The processing application will decide the style and numbering of lists.

Ordered list items can have multiple paragraphs and nested lists just like unordered lists, and ordered and unordered list can be nested inside each other.

Labeled lists begin with a label between pipe characters. There must be no space between the opening pipe character and the start of the label text. (Otherwise it will be parsed as a line, not a labeled list.

|fa| A long long way to run.
|so| A needle pulling thread.
|la| A note to follow so.

As with other lists, the content of a list item is a paragraph and you can add other structures after the initial paragraph by adding them at the same indent as the first paragraph. (The start of the paragraph, not the label.)

|Do| a deer,
a female deer
|Re| a drop of
     golden sun

     Is it a particle or a wave?


|Me| a name I call myself

A grid is created by starting a line with three + signs. These may be followed by block annotations.

Each row of the grid is on a separate line. Cells are separated by pipes. There is no pipe before the first cell or after the last. All rows must have the same number of cells.

There is no concept of a header, no row or column spanning. A grid consists of rows and cells. Each cell contains a single flow. Each row must be on one line of the source files. Cell contents are trimmed of leading and trailing whitespace. This allows you to align the pipes if you wish (though this is not required).

+++
    *Type*  | *Term*    | *Notes*

    feature | fragment  | bing

    feature | fragments | bang

Management attributes are permitted on the grid, but not the rows.

+++(*foo #bar ?baz)
    *Type*  | *Term*    | *Notes*

    feature | fragment  | bing

    feature | fragments | bang

A comment is created by starting a line with a #. There is no support for multi-line comments or for comments within running text.

# This is a comment.

A remark looks like a blockquote except that is is introduced with three ! characters and takes a attribution attribute:

!!!(Mark Baker) 
    This is a remark.

The body of a remark is normal SAM so it can contain other SAM structures.

Remarks can take a id or language attribute, but not a name or condition attribute.

Remarks are a block structure. There is not provision for including a remark in the middle of a paragraph. Generally, speaking, placing a remark after the paragraph it remarks on should be sufficient, however, if you want to anchor a remark to a specific spot in a paragraph, you can do so by giving the remark an ID attribute and referring to it using a citation:

This requires a remark[*cdg1], but the paragraph continues.

!!!(Charles André Joseph Marie de Gaulle)(*cdg1)(!fr)
    La Plume de ma tante.

Decoration are indicated by characters in the text that bracket phrases. The decorations are as follows:

• * is a decoration for bold.

• _ is a decoration for italic

Examples:

This text is in *bold* type.

This text is _italic_ type.

Decorations cannot be nested, so

This text is *_important_*.

is not a shortcut for

This text is {important}(bold)(italic)

but would be interpreted as

This text is {_important_}(bold).

Decorations are not recognized inside of phrases, since decorations are shorcuts for phrases and phrases cannot be nested. Decoration characters inside annotations are read as plain text.

Annotation chaining is supported for decorations. Therefore if you want to make text both both and italic, you could use:

This text is *important*(italic)

Although it may be clearer to do this:

This text is {important}(bold)(italic)

{Moby Dick}(book) is about a whale.

_Moby Dick_ is about a whale.

{Moby Dick}+(italic) is about a whale.

{Moby Dick}+(italic) is a {very}+(emphasis) good book.

<p>This text is in <bold>bold</bold> type.</p>

<p>This text is <italic>italic</italic> type.</p>

<p>This text is in <b class="bold">bold</b> type.</p>

<p>This text is <i class="italic">italic</i> type.</p>

Inline code is indicated by surrounding it in backticks:

In Python 3, use `print("Hello World")`. 

The body of an inline code structure is not parsed for character escapes or other markup, so you can do this:

In SAM, a phrase looks like this: `{phrase}`.

The only character that can be escaped in inline code is the back tick, which is escaped using a double back tick: `.

In Python 3, use `print("Hello World")`(python). 

Inline code can also take all the regular attributes.

In the correct form is `print("Hello World")`(python)(?p3)`print "Hello World`(python)(?p2). 

Inline code cannot take chained annotations, however.

An inline embed looks exactly like inline code except that it has an annotation containing an encoding attribute, which it the name of the encoding language preceded by a =:

This is an equation `\frac{ \sum_{t=0}^{N}f(t,k) }{N}`(=latexmath) in the middle of a paragraph. 

A variable definition is created by the appropriate indent followed by a $ and a name-like-string followed by an = and the value of the variable. The variable value ends at the end of the current line:

$foo = bar

The variable can then be inserted using a block insert or inline insert:

The sentence includes a string insert >($foo).

>>>($foo)

Variable definitions do not take any attributes. The variable name is a name token.

In XML output mode, the resolution of variables is left to the application layer. This allows the application layer to consider variables definitions from outside the local file.

In HTML output mode, variables are resolved using definitions in the local file. A warning is issued if the variable cannot be resolved and the insertion is skipped.

Fragments are created beginning a line with the ~ characters:

This paragraph is outside the fragment.

~~~(?foo)

    This paragraph is inside the fragment and should only appear if the {condition} `foo` is true.

This paragraph is outside the fragment again and will always be included.

You can allow for the redefinition of parts of the text of a fragment by defining a variable inside a fragment and use that variable in the definition of the fragment text:

~~~(#my-fragment) 
    $color=black 

To insert a fragment:

>>>(#my-fragment)

As per the variable scoping rules, any redefinition of those variable as children of the insert will override the values in the fragment. Thus:

>>>(#my-fragment)
    $color=white

should be resolved to:

Bar bar white sheep Have you any wool?

(But remember that variable resolution is performed by the application layer in XML output mode but by the SAM parser in HTML output mode.)

An include is indicated by the appropriate indent, followed by three less-than signs, followed by the path to a SAM file in parentheses.

<<<(foo.sam)