NML

  NML is no markup language.  It thus stands for No Markup Language.

§ Block Structures

    An NML document consists of a title, a number of blocks, followed by a number
    of sections.  Before we describe these entities, we need to state that blocks
    are separated by a non-empty sequence of empty (blank) lines.

  § Document Title

      An NML document’s title consists of the first non-empty sequence of
      lines, which, in turn, of course consist of inlines.  It is customary for
      an NML document’s title to be centered.  This document’s title was
      written as

                                              NML

  § Paragraphs

      A paragraph consists of a non-empty sequence of lines, indented by
      2×(1+n) spaces, where /n/ is the current section level (nesting).  The
      first paragraph of this document was thus written as

          NML is no markup language.

      Actually, this indention rule is common for all block elements.  That is,
      the current indention tells you how deeply you are nested and tells an
      NML processor how to properly treat different elements in the document.

  § Code Blocks

      A code block consists of a non-empty sequence of lines, indented by two
      spaces in addition to the current indention level (see the discussion in
      the previous section).  Thus, the code block from the previous section
      was written as

                  NML is no markup language.

      Empty lines are skipped, so don’t require the indention to be present.

      The contents of a code block is left completely unprocessed, so you don’t
      need to worry about markup characters getting in the way.

  § Enumerations

      An enumeration – an ordered list – consists of a non-empty sequence of
      enumerated items.  An item consists of a list-item number followed by
      three spaces, then followed by a non-empty sequence of inlines.  This
      sequence can then be followed by any number of block-level elements.
      These block-level elements will be one level further in than the item
      itself, so the indention will be 2×(2+n), where /n/ is the current
      section level.

      The list

    ₁   This is item 1.
    ₂   This is item 2.

        It consists of two paragraphs.
    ₃   This is item 3.

      is thus written as

        ₁   This is item 1.
        ₂   This is item 2.

            It consists of two paragraphs.
        ₃   This is item 3.

      Perhaps you caught on to the reason for the three spaces?  Though not
      strictly necessary for being able to unambiguously parse the first line,
      they are nonetheless needed for the aesthetics of having them line up
      with any following block elements.  Having this additional indent also
      makes it possible to have more than nine items in the list and easier to
      see the numerals.

  § Itemizations

      An itemization – an unordered list – works the same way as an enumeration.
      The only difference is that a bullet is used instead of list-item numbers:

        •   This is item 1
        •   This is item 2
        •   Item 3 here

      renders

    •   This is item 1
    •   This is item 2
    •   Item 3 here

  § Definitions

    = Definitions
        Definitions are a non-empty sequence of definitions.
    = Definition
        A definition consists of a non-empty sequence of terms, followed by a
        sequence of blocks that constite the definition
    = Term
        A term is a sequence of inlines preceded by ‹= › in the indention.

      The above list was thus written as

        = Definitions
            Definitions are a non-empty sequence of definitions.
        = Definition
            A definition consists of a non-empty sequence of terms, followed by
            a sequence of blocks that constite the definition
        = Term
            A term is a sequence of inlines preceded by ‹= › in the indention.

      You can define many terms that have the same definition at once by
      listing each of them before the definition:

        = A
        = B
            Definition that defines both A and B.

      Terms may span multiple lines, but following lines must then not be
      indented more than necessary:

        = A long term that
          requires multiple lines to name
            The terms definition goes here.

      If the second line in the example above was indented any further it would
      have been seen as the start of the definition of the term.

  § Quotes

      Quotes consists of a non-empty sequence of lines.  Each line consists of
      a non-empty sequence of inlines.  To quote Shakespeare:

    > To clique, or not to clique, that is the question:
    > Whether ’tis nobler in the mind to suffer
    > The slings and arrows of outrageous fortune,
    > Or to take arms against a sea of troubles,
    > And by opposing end them?

      Here, each line is an actual line from Hamlet.  It was rendered by

        > To clique, or not to clique, that is the question:
        > Whether 'tis nobler in the mind to suffer
        > The slings and arrows of outrageous fortune,
        > Or to take arms against a sea of troubles,
        > And by opposing end them?

      Sometimes you want a quote to span multiple lines, but only actually
      render as one.  In that case you simply replace the ‹>› with ‹ ›, that
      is, a space (‘ ’).  Let’s use the following quote, due to Antoine de
      Saint-Exupéry, as an example:

    > Perfection (in design) is achieved not when there is nothing more to
      add, but rather when there is nothing more to take away.
    — Antoine de Saint-Exupéry

      This was written as

        > Perfection (in design) is achieved not when there is nothing more to
          add, but rather when there is nothing more to take away.
        — Antoine de Saint-Exupéry

      This example also introduced the attribution line.  The attribution line
      is optional and may directly follow the lines of the quote.  It is
      introduced with ‹— ›, that is, an em dash, ‘—’, followed by a space, ‘ ’.

  § Tables

      Tables consist of a head and a body.  The head consists of one row.  The
      body consists of one or more rows.  Each row consists of one or more
      cells.  Cells are demarkated by ‘|’s.  The first cell demarkation symbol
      appears at the beginning of the normal indention.  Thus, the table

    | Part  | Consists of |
    | Table | Head, Body  |
    | Head  | Row         |
    | Body  | Rows        |
    | Row   | Cells       |

      is written as

          Thus, the table

        | Part  | Consists of |
        | Table | Head, Body  |
        | Head  | Row         |
        | Body  | Rows        |
        | Row   | Cells       |

          is written as

        …

  § Footnotes

      Any block may be followed by a list of footnotes.  Footnotes are usually
      used for various inlines that lack a decent syntax.  Footnotes consist of
      an identifier followed by a space followed by the footnote definition.
      Valid footnote identifiers are ‹¹›, ‹²›, ‹³›, ‹⁴›, ‹⁵›, ‹⁶›, ‹⁷›, ‹⁸›,
      ‹⁹›.

      Footnote definitions aren’t free-form and must follow a set of patterns.
      Here’s an example:

          Drop me a line¹.

        ¹ Email me at mailto:example@example.com

      This is a paragraph consisting of the text “Drop me a line”.  The word
      “line” has a footnote associated with it (identified by ‹¹›).  The
      footnote is defined as a link to “mailto:example@example.com”.  The link
      title will be “Email me”.  In the NML markup this will be converted to

        <p>Drop me a
          <ref title="Email me" uri="mailto:example@example.com">line</ref></p>

      The identifiers don’t have to come in order, which makes re-ordering
      unnecessary in the event that footnotes are added and deleted during
      editing.

      Footnotes nest, so you don’t have to define a footnote as soon as
      possible.  You can, for example, leave all footnoting of a list’s items
      to the list as a whole.  (In fact, you can’t define footnotes for the
      first paragraph of an item anyway.  This is a limitation that may be
      lifted in the future, but it’s really not that much of a limitation, as
      having footnotes sprinkled inside your lists makes for very messy lists.
      In fact, having blocks in your lists at all is sort of messy, but I
      digress…)

§ Sections

    Sections consist of a title, followed by a sequence of empty lines, then a
    sequence of blocks, another sequences of empty lines, and finally a
    sequence of subsections.  Sections can currently only be nested to two
    levels.  The first section of this document was written as

      § Block Structures

          An NML document consists of a title, a number of blocks, followed …

    Here you see that start of a new section is identified by a ‘§’ followed by
    the section title.  The blocks are, as you see, indented in the manner
    described earlier.

§ Inlines

    Inlines consist of a sequence of words or inline types (described below)
    separated by whitespace or punctuation.  All whitespace is normalized into
    one space character, ‘ ’.

  § Abbreviations

      Abbreviations are defined using footnotes.  Defining an abbreviation,
      such as NML¹, looks like

    ¹ Abbreviation for Neat Markup Language

          Defining an abbreviation, such as NML¹, looks like
        
        ¹ Abbreviation for Neat Markup Language

      Any text that follows ‹Abbreviation for› will be used as the definition
      of the abbreviation.

  § Code

      Inline code is surrounded by ‹‹› and ‹››.  Taking a line earlier in this
      document as an example, we thus have

        Valid footnote identifiers are ‹¹›, ‹²›, …

      The contents inside a code inline is left completely unprocessed.  You
      can thus use code inlines to write characters that would otherwise be
      seen as special for NML, as long as it makes sense to mark them as code.
      The end character, ‘›’, can occur at the end of a code inline, for
      example, ‹‹code is written like this››, by following the last ‹›› by
      another ‹››.

  § Emphasis

      Emphasis is written like ‹/this/›.  Emphasis doesn’t nest.  The ending
      solidus, ‘/’, will only be seen as an ending emphasis if it’s not
      followed by another solidus.

  § Escaped Characters

      To be able to write characters that would otherwise be seen as special
      for NML, escaped characters, may be used.  Escaped characters are written
      as ‹‘c’›, where /c/ is the character to escape.  Note how well this
      meshes with the standard practice of surrounding a character with single
      quotes in English when you are referring to the character itself.  Also
      note that the single quotes will be retained in any output, as the whole
      sequence is simply seen as text.

  § Groups

      Sometimes you want a footnote to refer to more than one inline.  You can
      then group a number of inlines by surrounding them with ‹{› and ‹}›:

        {Drop me a line}¹.

      Here, footnote ‹¹› will refer to the words “Drop me a line”.  Groups
      nest.

  § Footnotes

      Footnotes may be added to any inline by appending them to it.  More than
      one footnote may be added by separating the footnotes with a ‹⁺›.
      Footnotes are processed left to right, so the leftmost will be the
      innermost one in the AST/XML representation.  Thus,

        {Drop me a line}¹⁺²

      will be represented by the following (imaginary) XML structure

        <footnote identifier="²">
          <footnote identifier="¹">
            <group>Drop me a line</group>
          </footnote>
        </footnote>

  § Links

      Links are defined using footnotes.  You can, for example, link to
      http://example.com¹ by writing

    ¹ Visit IANA’s example domain page at http://example.com/

          You can, for example, link to http://example.com¹ by writing

        ¹ Visit IANA’s example domain page at http://example.com/

      Link definitions are rather free-form.  They contain a title, which can
      be any string, followed by the word ‹at›, followed by a non-empty
      sequence of non-space characters that constitute the uniform resource
      identifier (URI) that the link should point to.