Note: This file is created using cxt. To see the source view README.cxt in this directory.

It should not take more than a few minutes to know how to read and write documentation.

cxt is an ultra-simple markup language similar in spirit to BBCode , designed to be as easy as possible to parse (for computers and humans) while delivering any features necessary to the CivBoot project.

cxt is designed to:

• Make document writing easy.
• Make document parsing easy.
• Make reading of raw (text) documents easy.
• Make consuming structured data from documents easy.

cxt enables (for example) writing a command line utility's documentation as a .cxt file, parsing it and exporting it into a structed data format (aka json) and injesting that to generate code for the args structure of a program.

This repository is almost complete. It is certainly useable for many projects. Current progress:

• ✅ parsing text
• ✅ parsing code
• ✅ parsing lists
• ✅ export above to html or markdown-embedded html
• ✅ quotes (markdown >)
• ✅ set/get "variables"
• ✅ checkboxes
• ✅ comments (!)
• 🔲 parsing tables
• 🔲 enable export to json and zoa

Note: "cxt" is pronounced as either "C-X-T" or "text" with a 'c', at your discression.

Inline code:

Some `inline code`, more [#]inline code[#].

Some inline code , more inline code .

Formatting:

This sentance has [b]bold[b] text, [i]italic[i] text, and
[b][i]bold italic[i][b] text.

This sentance has bold text, italic text, and bold italic text.

Linking:

A url to [t r=http://civboot.org]CivBoot[/],
or displaying and linking the full url:
[r]http://civboot.org[/]

Alternatively, you can use set/get: @CivBoot

You can even use [@] for attributes like `r` (ref),
i.e. [t r=@civbootUrl]check out civboot![/]

[t set=CivBoot r=https://civboot.org]CivBoot[/]
[r set=civbootUrl]http://civboot.org[/]

A url to CivBoot , or displaying and linking the full url: http://civboot.org

Alternatively, you can use set/get: CivBoot

You can even use @ for attributes like r (ref), i.e. check out civboot!

Lists:

• bullet point
• second bullet point

[+]
 * bullet point
 * second bullet point
[/]

Numbered Lists:

[+]
 1. first item
 2. second item
 4. fourth item?
[/]

1. first item
2. second item
4. fourth item?

Sub Lists:

[+]
 * Bullet point [+]
   * Sub bullet point
 [/]
 * Second bullet point
[/]

• Bullet point
  • Sub bullet point
• Second bullet point

Checkboxes:

[+]
 [X] done item
 [ ] undone item [+]
   [X] indented done item
   [ ] indented undone item
 [/]
[/]

• ✅ done item
• 🔲 undone item
  • ✅ indended done item
  • 🔲 indended undone item

Developer-only Comments

The following comments are not rendered...
[!]This is a comment[/]
[t !]In fact, any block with a ! attr is a comment.[/]

The following comment is not rendered...

This is a backtick: [`]

Doubling a bracket escapes it. [[ This is in literal brackets ]]

An empty brackets like "[]" does nothing.
[]   This is useful for leading whitespace.

This is a backtick: `

Doubling a bracket escapes it. [ This is in literal brackets ]

An empty brackets like "" does nothing. This is useful for leading whitespace.

Empty brackets at the end of the line
cause it to continue.
This is useful for very-very-very-very-very-[
]very long words.
(notice: no spaces before last "very")

Empty brackets at the end of the line cause it to continue. This is useful for very-very-very-very-very-very long words. (notice: no spaces before last "very")

[table]
[h] Col1 | Col2 | Col3 [/]
[r] a1   | a2   | a3   [/]
[r] multi| b2   | b3
    line |      |
    row  |      |      [/]
[/]

• The delimiter can be specified with del. Example: [table del=;]
• Cell values are stipped (leading/trailing whitespace removed). If you want to force it, you can use [t] my cell value [/]

Special characters

 [[   literal open bracket
 ]]   literal close bracket
 [`]  literal backtick
 `inline code` (same as markdown)
 [c]inline code[c]
 [#...]inline code[#...]

Other literals:

• [n] literal newline \n
• [s] literal space character (used rarely)
• [] ignored (sometimes used if leading spaces ignored, i.e. in lists)

Text markup state: these toggle the current text state (not turned off with [/] :

• [i] italic
• [b] bold
• [~] strikethrough
• [u] underline

Containers:

• [!] comment. Inner text not rendered.
• [t] starts a "text container" where attributes can be applied.
• [r] reference container.
• [h1] heading 1
• [h2] heading 2
• [h3] heading 3
• [... mark=markName] creates a mark that can be linked with [r]
• [+] starts a list. The first non-whitespace character determines the list type (*, 1., [ ], [X])
• [table] table containing a header [h]...[/] and rows [r]...[/], delinited by a del (default |)

Attributes are added in attr=foo form:

• ! at end causes item to be "hidden"
• mark: attribute which creates a mark that can be linked [l] to.
• r: works like [r] but can be used like: [t r=foo]...[/]
• otherwise it is a "custom" attribute, some tools process these (i.e. lang for code, etc)

To build the README.md and run the tests, simply run make .

When opening a PR to submit code to this repository you must include the following disclaimer in your first commit message:

I <author> assent to license this and all future contributions to this project
under the dual licenses of the UNLICENSE or MIT license listed in the
`UNLICENSE` and `README.md` files of this repository.

This work is part of the Civboot project and therefore primarily exists for educational purposes. Attribution to the authors and project is appreciated but not necessary.

Therefore this body of work is licensed using the UNLICENSE unless otherwise specified at the beginning of the source file.

If for any reason the UNLICENSE is not valid in your jurisdiction or project, this work can be singly or dual licensed at your discression with the MIT license below.

Copyright 2022 Garrett Berg

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.