cxt: text markup for civilization

It should not take more than a few minutes to know how to read and write documentation.
cxt is an ultra-simple markup language which is designed to be as easy as possible to parse (for computers and humans) while still using as few characters as possible to express format for common cases. The src/ dir of CommonMark contains more than 20,000 lines of code whereas cxt is implemented in less than 500.
cxt is designed to:

Make document writing easy: use relatively few characters to express common formatting
Make document parsing easy: unambiguous, unlike Ma**rk_do*wn
Readable as raw text
structured data can be consumed: supports arbitrary attributes

CXT contains only three special characters for deliniating formatting controls:

the two bracket characters []
a way to escape brackets and itself \\, \[ and \]

There are two ways to specify attributes for a block:

short: [*bold text] where * can be any of the shortcuts below
full: [{*_ attr1 attr2=value}bold underlined with attr 1 and 2]

The following attributes and shortcuts are supported

  b i u   bold (*), italic (,) and underlined (_)

  * , _   Example: [*bold] [,italic] [_underlined]

                   [{*,_}bold italic and underlined]

  code    inline or block code (depending on whether newlines exist)

   $      shortcut: [$inline code]

   $$...  shortcut: [$$inline code]$  (close is one less than open)

          Can also use inside {} to require extra $ to close:

          [{$$ code=html}

          <b>example html</b>

          ]$

  quote   create a quote block

   "      Example: ["quote block]

  list    list syntax, see demos

   +      Example: [+

            * list item 1

            * list item 2

          ]

  table   table syntax, see demos.

  # head  modify the delimiters with row/col/head attrs.

  + row

  | col

  hidden  hidden block, used for comments and/or assigning attributes

   !      Example: [!hidden block]

  href    hyper reference, aka a url.

  <href>

   path   a path, typically relative to project or website root.

    /     Example: [/path/to/file.lua]

  name    sets the name of the block.

   n      Used with: [@name]  href=#name  anyAttr=@name

   :      shortcut: [{: ...}name]

          Example: [{name=Civboot href=http://civboot.org}Civboot]

          Example: [{: href=http://civboot.org}Civboot]

          You can link to the named item with [<#name>link to name].

  value   when @ is used for an attr value, it will get this attribute.

   v      defaults to "href" if the node has one, else "text" which

          is the node's text.

   @      copies a block with given name. When used as an attr value

          it gets the attribute referenced by "value"

          Example:

            [{!:href=http://civboot.org}Civboot] creates a hidden named block

            [@Civboot] clones the block (removing name and hidden)

            [<@Civboot>Civboot Project] has href=http://civboot.org

              note: the default for "value" is "href" if it exists.

 escapes

   \[    literal [

   \]    literal ]

   \\    literal \

   \*    literal \*, where * is any other character

Note: Any value after a bracket besides {...} b i u * , _ $ " + ! / : v @ is invalid.

Demos

Inline Code:

[$inline code]. Note that [$$ [brackets] need ]$

inline code. Note that [brackets] need

The number of $ at the end of a code block is one less than the number used to open it.

Code block:

Writing this:

[{$$ lang=lua}

function example()

  print'Hello world'

end

]$

Will create a formatted code block:

function example()

  print'Hello world'

end

Text Formatting

[*bold], [,italic] and [_underlined]

bold, italic and underlined

Linking

[{b i href=http://civboot.org}bold italic link]

bold italic link

List

Lists are started with +, each items is deliniated by *:

A list of stuff: [+

* example list

* with sub list:[+

  * sub item

  * multi-line

    sub item.

  * inner code block

    [$$

    function example()

      print'example inner block'

    end

    ]$

  * final sub

]

* final item

]

A list of stuff:

example list
with sub list:
- sub item
- multi-line
  sub item.
- inner code block
  function example()
  print'example inner block'
  end
- final sub
final item

Hidden

Hidden block: "[! this is hidden]"

Hidden block: ""

Table

A table is created by the 'table' attribute. We also set the head, row and col to the defaults for demonstration (they can be excluded). The row and head deliminters are only recognized at the start of a line.

A table: [{table head=# row=+ col=|}

# col 1      | col 2   | col 3

+ row [*1.1] | row 1.2 | row 1.3

+ row [*1.1] | row 1.2 | row 1.3

]

A table:

col 1	col 2	col 3
row 1.1	row 1.2	row 1.3
row 1.1	row 1.2	row 1.3

Table with large columns

For very large or multi-lined columns, you can organize them similar to sub-lists:

[{table}

# 1st header column

| 2nd header column

| 3rd header column

+ long row 1.1

| long row 1.2

  Even includes new line!

| long row 1.3

  [{$$ code=lua}

  function example()

    return "code block"

  end

  ]$

+ row 2.1

| row 2.2

| row 2.3

]

1st header column	2nd header column	3rd header column
long row 1.1	long row 1.2 Even includes new line!	long row 1.3 function example() return "code block" end
row 2.1	row 2.2	row 2.3

Named Nodes and Values

Note: all visible named blocks have a ☍ link next to them and serve dual purpose of being referenced within the cxt file using [@name] and by local and external links (href=#name)

A hidden named block: "[{!:href=http://civboot.org}Civboot]"

A hidden named block: ""

A visible named block: [{:href=https://github.com/civboot/civlua}civlua]] [+

* A visible named block: [{:href=https://github.com/civboot/civlua}civlua]

[@Civboot] clones the hidden block (removing the [$clone] attribute)] [+

* [@Civboot] clones the hidden block (removing the [$clone] attribute)

[<@Civboot>Civboot Project] has [$href=http://civboot.org].][+

* [<@Civboot>Civboot Project] has [$href=http://civboot.org].

You can also link to named blocks with [$href=#name], for instance the "Demos"

header is named [<#Demos>Demos].

You can also link to named blocks with href=#name, for instance the "Demos" header is named Demos.

Escaping [brackets]

You can \[escape\] brackets to render them directly.

You can also escape '\\'.

You can [escape] brackets to render them directly. You can also escape '\'.

UNLICENSE

Cxt is in the the public domain, see the UNLICENSE for details.
It was originally created by Rett Berg as part of the Civboot project.

Mod cxt

TODO: see TODO.cxt
Types: Config Writer Html
Functions

fn escape(str) -> str:gsub('([\\%[%]])', '\\%1')
escape the string so it renders literally
fn code(str, lang)
create [$inline code]
fn content(p, node, isRoot, altEnd)
parse normal content, adding to node
fn parse(dat, dbg)
fn checkParse(dat, context) -> dat
fn parsedStrings(p, node)
fn assertParse(dat, expected, dbg) -> node
fn assertThrows(dat, err, dbg)