path: root/MDOWN

%mdown 2.0
%? mdown core features
%? Nhat Minh Lê <nhat.minh.le@huoc.org>

# Meta-info markup

## Comments

Comments are lines beginning (at column 0) with any number of percent
signs, followed by space.

:Rationale:
  This reserves constructs for directives without hurting readability.

## Directives

Directives are lines beginning (at column 0) with a percent sign, not
followed by space. Most directives are ignored by mdown.

:Rationale:
  Most static preprocessors operate on lines. Such directives leave
  the opportunity for such preprocessors to be added. For more complex
  handling of contents, you should use macros and environments with
  appropriate dynamic element translation.

### Version directive

Each mdown document must start with the version directive `%mdown`,
followed by the version of the mdown language in use in the
document. The only valid value defined by this specification is `2.0`.

Only comments and blank lines are allowed before the version
directive.

:Rationale:
  The intent is quite obviously that new versions of mdown will
  increment the version number.

### Line directives

The `%#` directive followed by a numeric (all-digit) word `N`
indicates that the following line should be referred to as the `N`^th
line of the current file.

The `%#` directive followed by a numeric word `N` and an arbitrary
string (with leading spaces stripped) specifies a new file name in
addition to the new line number.

### Bibliographic directives

The first three occurrences of the `%?` directive are special to mdown
and recognized as bibliograhic information. In order, they specify, in
plain text, the name of the document, the name of the author or
authors, and the date of publication.

:Rationale:
  Plain text was chosen so that this information can be handled
  separately without having to invoke the mdown system. Since many
  output formats do not support formatting in titles anyway, the need
  for such support in mdown was deemed negligible.

### Annotation alias directives

A simple annotation (which takes no argument) can be defined by making
an alias of another annotation. It is the only way to specify
arguments for inline annotations.

An inline annotation alias is a `%@` directive followed by the name of
the annotation being defined, an equal sign, and the annotation name
and arguments of the aliased annotation.

A block annotation alias is a `%@@` directive that follows the same
syntax.

Definitions take effect immediately. Redefinitions are allowed and
take effect till the next redefinition or the end of the document.


# Inline markup

## Styling

| Symbol   | Syntax      | Effects                | Constraints            |
+----------+-------------+------------------------+------------------------+
| `\`      | `\a`        | escaped character      |                        |
| `\`      | `a\ b`      | unbreakable space      | before whitespace      |
| `\`      | `line \`    | forced line break      | at end of line         |
| `*`      | `*a*`       | emphasis               |                        |
| `**`     | `**a**`     | strong emphasis        |                        |
| `***`    | `***a***`   | very strong emphasis   |                        |
| `'`      | `'a'`       | alternate style        | lead-in/out            |
| `''`     | `''a''`     | strong alternate style | lead-in/out            |
| `` ` ``  | `` `a` ``   | code                   | matching, verbatim     |
| `$`      | `$a$`       | math                   | verbatim               |
| `^`      | `^a`        | superscript            | free group             |
| `@`      | `@c`        | special character      | symbol, matching       |
| `@`      | `@a`        | annotation             | free group             |
| `@`      | `@`         | repeat annotations     | free group             |
| `@"`     | `@"a"`      | inline quote           |                        |
| `@_`     | `@_a_`      | subscript              |                        |
| `@`      | `@a b`      | annotation             | named, free group      |
| `{}`     | `{a}`       | group                  | where free group       |

Some notes:

- Lead-in/out means the opening/closing symbol has to appear at word
  boundary on the external side of the element: that is, the opening
  symbol has to be preceded by white space or a punctuator that is
  actually interpreted by mdown, and the closing symbol must be
  followed by such a character.

- Matching means there can be more than one delimiter, but their
  number has to agree in a single element.

- Free group means the construct applies to the next syntactical
  group, which defaults to the next word.

- Named means the construct takes a name, which is an alphanumeric
  sequence.

:Rationale:
  The line-breaking character was changed from mdown-1 following many
  complaints that it was hard to spot and triggered hard-to-understand
  errors.

  Emphasis was changed from two different characters to a single
  stackable one for homogeneity, resemblance to [?Markdown], and
  because the slash is much used in addresses and paths.

  The alternate style construct was introduced after much
  consideration concluding that people don't usually care what
  language a word is actually written in, just that it is not native
  from the current language of the document. Besides, I believe it is
  natural for most people to pronounce unknown foreign words according
  to the rules of their native language, not some foreign rules they
  may or may not know. Thus, the alternate style replaces mdown-1
  foreign phrase constructs as well as language tags.

  The math symbol is taken from TeX.

## Links

| Symbol   | Syntax                 | Effects                   |
+----------+------------------------+---------------------------+
| `[]`     | `[text]`               | implicit hypertext link   |
|          | `[text](address)`      | explicit hypertext link   |
|          | `[text|label]`         | indirect hypertext link   |
| `[!]`    | `[!text]`              | implicit substitution     |
|          | `[!text](address)`     | explicit substitution     |
|          | `[!text|label]`        | indirect substitution     |
| `[^]`    | `[^label]`             | footnote                  |
| `[?]`    | `[?label]`             | bibliographic note        |

:Rationale:
  Implicit links replace the mdown-1 syntax for anchors: this is more
  consistent. Anchors have been changed to a declaration syntax.

  The indirect syntax was changed because of the introduction of
  implicit links. It resembles the Wiki syntax, but reversed, which
  may be awkward for some users, but I for one think that the Wiki
  order is not natural for semantic links.

## Constraints

Inline elements, even code spans, cannot cross block boundaries.

## Nesting

Markup may nest but the output format is free to ignore any nesting
and only consider the outermost level of inline markup for
translation.

Therefore, it is advised that links always be put at the outermost
level, and styling be inlined within the link text.

Though the syntax allows same constructs to nest, it does not usually
make sense to do so, and implementations are encouraged to disregard
such markup.

:Rationale:
  These rules allow parts of links to be emphasized or turned into
  images, while still providing a fallback for output environments
  where this kind of thing is not supported, in which case, the link
  behavior will prevail over the rest.


# Block markup

Indentation is made through steps of two spaces or right angle
brackets. An indented block is a block where each line (except the
first, and except blank lines) is indented by two spaces (added to the
current indentation level). In the following descriptions, the
beginning of a line (as in "line begins with") means at the current
level of indentation.

## Paragraphs

Paragraphs are unindented blocks (indented at the current indentation
level) delimited by blank lines or other constructs (in other words,
it is the default construct).

If a paragraph is preceded by blank lines, then it is a full
paragraph; if it is preceded by another block with no intervening
blank line, then it is continuation paragraph. Output formats are not
required to make a distinction. Comments do *not* count as blank
lines, meaning you can force a continuation by putting a comment in
place of a blank line.

Paragraphs cannot contain other blocks.

:Rationale:
  The rules for continuation paragraphs have been simplified so that
  each paragraph can now be treated separately. Continuation
  paragraphs are useful either in order to remove extra spacing in
  formats that use spacing to indicate paragraphs (e.g. most web
  designs) or ugly indentation in formats that use indentation to mark
  new paragraphs (e.g. LaTeX).

  This now lets you make compact lists simply by not leaving a blank
  line between the preceding paragraph and the list.

## Headings

Headings are lines beginning at column 0 with one to five hash signs,
the number of which determine the level (one being the most important)
of the heading.

Headings cannot contain other blocks.

:Rationale:
  After much thinking, the old wiki-like syntax was replaced with
  a [?Markdown]-compatible syntax, partly because in the end, I find
  it better-looking, partly since environments have had their syntax
  changed.

## Quotations

Quotations are indented blocks where the first line begins with
a right angle bracket and one space (each subsequent line may be
indented using such brackets as well, by definition of indentation).

## Verbatim blocks

Verbatim blocks are indented blocks where the first line begins with
two spaces (each subsequent line may be indented using such brackets
as well, by definition of indentation).

The content of verbatim blocks are not parsed by mdown.

## Math blocks

Math blocks are indented blocks where the first begins with two
dollars and one space.

The content of math blocks are not parsed by mdown.

## Lists

Lists are made of consecutive items. The syntax of the items determine
the type of the list.

### Unordered lists

Unordered list items are indented blocks where the first line begins
with a hyphen followed by one space.

### Ordered lists

Ordered list items are indented blocks where the first line begins
with an all-digit word (the number thus formed shall not be
meaningful, except maybe for the first element) followed by one dot
then one space.

### Associative lists

Associative list items are made of two blocks: one line (the head)
followed by an indented block (the body) where the first line
begins with a colon and one space.

## Tables

Tables are made of consecutive rows.

### Table rows

Table rows are indented blocks where the first line begins with
a vertical bar followed by a space. A table row contains table cells.

### Simple table cells

Simple table cells are inline elements ending with a space and
a vertical bar. As inline elements, simple cells cannot contain
blocks.

### Block table cells

Block table cells are indented blocks where the first line begins with
a plus sign followed by a space.

## Environments

Environments are indented blocks where the first line begins with
a colons followed by the class (environment name; a word), some
optional argument text, another colon, and an optional caption
text. Subsequent lines make up the contents of the environment.

## Block annotations

Blocks can be annotated. An annotation is a unindented line beginning
with two at signs, followed by the annotation name (a word), and some
optional argument text.

## Declarations

Some mdown constructs reference a label. Such a label is defined using
a declaration construct, which consists of an indented line where the
beginning with one space followed by the entity being declared. The
entity name is marked up the same way it is written when referenced,
with the text part and the eventual vertical bar separator
removed. The rest of the declaration block is treated verbatim as
a reference to some resource.

Declarations are allowed for links, anchors, substitutions, and
bibliographic references.

Anchors share the syntax of the corresponding links (i.e. a fragment
name beginning with a hash sign) and have no declaration body. The
declaration point is taken as the resource for the anchor.

## Indirect blocks

Indirect blocks are like declarations, except they allow inline
content and are used for footnotes and bibliographic references.

The first line of an indirect block follows the same syntax as
a declaration; subsequent lines are non-indented (i.e. as they would
in a paragraph). Hence, an indirect block cannot contain other blocks.


# Translation semantics

Are listed only things that are not obvious, for everything else, you
can ask me if you can't figure out, I may have forgotten some things.

## Implicit links handling

When using implicit links, the actual text and address are both
inferred from the given link.

1. If there is a label defined with the same name, then its address is
  used and the label itself is taken as the text.

2. Else, the link is taken to be an address.

3. For internal links: if there is a title associated with the
  referenced entity, then it is used as the text (for an anchor, it is
  the associated heading; for a document, it is its title; for a file
  it is its file name); else, the link is used.

4. For external links: the link is used as the text.

:Rationale:
  With the introduction of the internal address space, implicit links
  are intended to become the main type of links internal to
  a collection of mdown documents (e.g. a website). These were
  obviously inspired by Wiki links in which the explicit text is not
  often spelled out.

## Translation of dynamic elements

mdown delegates the exact handling of some elements (called dynamic
elements) to the outer environment in which the resulting document
will be used. These elements are annotations, environments, and
links. A default translation is used if the output format does not
support such processing.

This is intended to be used in conjunction with some kind of
scripting, to produce documents with partly-generated contents or
customizable styles.

For example, an implementation could generate a LaTeX document with
native macro and environment calls. Or it could produce a HTML
document with macros and environments translated to CSS classes. But
the same document could be translated to a mixed PHP/HTML document,
replacing macros and environments with calls to server-side functions
for contents generation.

:Rationale:
  This extends the simple environment translation mechanism of mdown-1
  into a more flexible interface, which will hopefully allow better
  integration with other tools and frameworks (mainly, website
  frameworks).


# References

 [?Crossmark] http://dev.laptop.org/git?p=users/krstic/docformat;a=blob_plain;f=crossmark-spec.txt;hb=HEAD
 [?Markdown] http://daringfireball.net/projects/markdown/
 [?Pandoc] http://johnmacfarlane.net/pandoc/
 [?ReST] http://docutils.sourceforge.net/rst.html