documentation.wrm

_section: Flatworm Docs @<flatworm>

The //Flatworm Docs// rendering engine is designed to be **very**
simple, but provide enough formatting necessary for documenting
JavaScript libraries.

A lot of its inspiration came from [Read the Docs](link-rtd) and
the [Sphinx](link-sphinx) project.


_subsection: Fragments @<flatworm-fragments>

Each page is made up of fragments. A fragment is a [directive](flatworm-directive),
with an value and optional //link//, //extensions// and a body.

Many directives support [markdown](flatworm-markdown) in their value and body.

A fragment's body continues until another fragment is encountered.


_heading: Directive Format

_code: @lang<text>

\_DIRECTIVE: VALUE @<LINK> @EXTENSION<PARAMETER>
BODY

MORE BODY

DIRECTIVE:  The directive name
VALUE:      Optional; the value to pass to the directive
LINK:       Optional; a name for internal linking
EXTENSION:  Optional; extended directive functionality
PARAMETER:  Optional; value to pass to extended directive functions
BODY:       Optional; the directive body (certain directives only)


_heading: Flatworm Directives @<flatworm-directive>

_definition: **_section:** //TITLE//
A //section// has its **TITLE** in an H1 font. Sections are linked
to in //Table of Contents// and have a dividing line drawn above
them.

The body supports markdown.

There should only be one ``_section:`` per page.

**Extensions:** [@inherit](flatworm--ext-inherit), [@src](flatworm--ext-src), [@nav](flatworm--ext-nav), [@note](flatworm--ext-note)

_definition: **_subsection:** //TITLE//
A //subsection// has its **TITLE** in an H2 font. Subsections are linked
to in //Table of Contents// and have a dividing line drawn above
them.

The title and body support markdown.

**Extensions:** [@inherit](flatworm--ext-inherit), [@src](flatworm--ext-src), [@note](flatworm--ext-note)

_definition: **_heading:** //TITLE//
A //heading// has its **TITLE** in an H3 font.

The title and body support markdown.

**Extensions:** [@inherit](flatworm--ext-inherit), [@src](flatworm--ext-src), [@note](flatworm--ext-note)

_definition: **_definition:** //TERM//
A //definition// has its **TERM** in normal text and the body is
indented.

The title and body support markdown.

_definition: **_property:** //SIGNATURE//
A //property// has its JavaScript **SIGNATURE** formatted.

The body supports markdown and the return portion of the signature
support markdown links.

**Extensions:** [@src](flatworm--ext-src)

_definition: **_note:** //BANNER//
A //note// is placed in a blue bordered-box to draw attention to it.

The body supports markdown.

_definition: **_warning:** //BANNER//
A //warning// is placed in an orange bordered-box to draw attention to it.

The body supports markdown.

_definition: **_code:** //CAPTION//
Creates a [Code](flatworm--code) block.

The body does **not** support markdown, and will be output exactly as
is, with the exception of [Code Evaluation](flatworm--code-eval).

If a line begins with a ``"_"``, it should be escaped with a ``"\\"``.

**Extensions:** [@lang](flatworm--ext-lang)

_definition: **_table:** //FOOTER//

Creates a [Table](flatworm--table) structured according to the body.

Each cell contents supports markdown and variables supports markdown.

**Extensions:** [@style](flatworm--ext-style)

_definition: **_toc:**
A //toc// injects a Table of Contents, loading each line of the
body as a filename and recursively loads the //toc// if present,
otherwise all the //sections// and //subsections//.

The body does **not** support markdown, as it is interpreted as
a list of files and directories to process.

_definition: **_null:**
A //null// is used to terminated a directive. For example, after
a //definition//, the bodies are indented, so a //null// can be
used to reset the indentation.

The body supports markdown.

_code: Example @lang<text>

\_section: Hello World @<link-main>
Body for section...


\_subsection: Some Example @<link-secondary>
Body for subsection...


\_heading: Large Bold Text @<link-here>
Body for heading...


\_definition: Flatworm
A phylum of relatively **simple** bilaterian, unsegmented,
soft-bodied invertebrates.


\_property: String.fromCharCode(code) => string
Returns a string created from //code//, a sequence of
UTF-16 code units.


\_code: heading

// Some code goes here
while(1);


\_table: Table Footer

|  **Name**  |  **Color**  |
|   Apple    |   Red       |
|   Banana   |   Yellow    |
|   Grape    |   Purple    |


\_toc:
    some-file
    some-directory


\_note: Title
This is placed in a blue box.


\_warning: Title
This is placed in an orange box.


\_null:
This breaks out of a directive. For example, to end
a ``_note:`` or ``_code:``.


_subsection: Markdown @<flatworm-markdown>

The markdown is simple and does not have the flexibility of
other dialects, but allows for **bold**, //italic//,
__underlined__, ``monospaced``, super^^script^^ and ~~strike~~
text, supporting [links](flatworm-markdown) and lists.

Lists are rendered as blocks of a body, so cannot be used within
a title or within another list.

_code: @lang<text>

**bold text**

//italic text//

__underlined text__

``monospace code``

^^superscript text^^

~~strikeout text~~

- This is a list
- With bullet points
- With a total of three items

This is a [Link to Ethereum](https://ethereum.org) and this
is an [Internal Link](some-link).

This is a self-titled link [[https://ethereumorg]] and this
[[some-link]] will use the title from its directives value.


_subsection: Code @<flatworm--code>

The code directive creates a monospace, contained block useful
for displaying code samples.

_heading: JavaScript Evaluation @<flatworm--code-eval>

For JavaScript files, the file is transpiled and executed in a VM,
allowiung output (or exceptions) of blocks to be included in the
fragment output.

The entire **code fragment** source is included in an async IIFE,
whick means ``await`` is allowed, and several special comment
directives are allowed.

A ``/\/_hide:`` will include any following code directly into the
output, but will not include it in the generated output for the fragment.

A ``/\/_log:`` will include the value of any following expression in the
output, prefixed with a ``/\/ ``. Renderers will mark output in different
style if possible.

A ``/\/_result:`` will begin a block, assigning the contents to ``_``. The
block can be ended with a ``/\/_log:`` or ``/\/_null:``, if no value is given
to log, then ``_`` is assumed. If an error occurs, generation fails.

A ``/\/_throws:`` will begin a block, which is expected to throw assigning
the error to ``_``. The block can be ended with a ``/\/_log:`` or ``/\/_null:``,
if no value is given to log, then ``_`` is assumed. If an error do not occur,
generation fails.

_code: Code Evaluation Example @lang<text>

\_code: Result of Code Example  @lang<javascript>

//_hide: const url = require("url");

//_result:
url.parse("https://www.ricmoo.com/").protocol
//_log:

//_throws:
url.parse(45)
//_log:

// You want to assign (doesn't emit eval) AND display the value
const foo = 4 + 5;
//_log: foo


_code: Result of Code Example  @lang<javascript>

//_hide: const url = require("url");

//_result:
url.parse("https://www.ricmoo.com/").protocol
//_log:

//_throws:
url.parse(45)
//_log:

// You want to assign (doesn't emit eval) AND display the value
const foo = 4 + 5;
//_log: foo


_heading: Languages

The language can be specified using the [@lang extension](flatworm--ext-lang).

_table:

|  **Language**  |                             **Notes**                                    |
|   javascript   | Syntax highlights and [evaluates](flatworm--code-eval) the JavaScript    |
|   script       | Same as ``javascript``, but does not evaluate the results                |
|   shell        | Shell scripts or command-line                                            |
|   text         | Plain text with no syntax highlighting                                   |

_subsection: Tables @<flatworm--table>

The table directive consumes the entire body up until the next
directive. To terminate a table early to begin a text block,
use a **_null:** directive.

Each line of the body should be [Row Data](flatworm--table-row) or a
[Variable Declaration](flatworm--table-variable) (or continuation of
a //Variable Declaration//). Blank lines are ignored.

_heading: Row Data @<flatworm--table-row>

Each **Row Data** line must begin and end with a **``"|"``**, with each
gap representing the cell data, [alignment](flatworm--table-alignment)
with optional [column and row spanning](flatworm--table-spanning).


_heading: Alignment @<flatworm--table-alignment>

The alignment for a cell is determined by the whitespace surrounding the
cell data.

_table: Alignment Conditions (higher precedence listed first)

|   **Alignment**   |                    **Whitespace**                     |
|    //Left//       | 1 or fewer spaces before the content                  |
|    //Right//      | 1 or fewer spaces after the content                   |
|    //Center//     | 2 or more space **both** before and after the content |


_code: Alignment Example @lang<text>

\_table: Result of Alignment Example @style<compact>

|   center    |

| left        |
|left         |

|       right |
|        right|

_table: Result of Alignment Example @style<compact>

|   center    |

| left        |
|left         |

|       right |
|        right|


_heading: Row and Column Spanning @<flatworm--table-spanning>

A column may end its content with any number of **``"<"``** which indicates
how many //additional// columns to extend into.

If the cell content contains only a **``"^"``**, then the row above is
extended into this cell (into the same number of columns).

_code: Cell Spanning Example @lang<text>

\_table: Result of Cell Spanning Example @style<compact>

|  (1x1)  |  (1x2)      <|  (2x1)  |
|  (2x2)      <|  (2x1)  |    ^    |
|    ^         |    ^    |  (1x1)  |

_table: Result of Cell Spanning Example @style<compact>

|  (1x1)  |  (1x2)      <|  (2x1)  |
|  (2x2)      <|  (2x1)  |    ^    |
|    ^         |    ^    |  (1x1)  |


_heading: Styles  @<flatworm--table-style>

The [@style extension](flatworm--ext-style) for a table can be used to control its
appearance.

_table:

|   **Name**    |    **Width**    |  **Columns**       |
|  //minimal//  |   minimum size  |    best fit        |
|  //compact//  |     40%         |    evenly spaced   |
|   //wide//    |     67%         |    evenly spaced   |
|   //full//    |    100%         |    evenly spaced   |


_heading: Variables  @<flatworm--table-variable>

Often the layout of a table is easier to express and maintain without
uneven or changing content within it. So the content can be defined
separately within a table directive using **variables**. A variable
name must begin with a letter and must only contain letters and numbers.

Variables are also useful when content is repeated throughout a table.

A variable is declared by starting a line with ``"$NAME:"``, which
consumes all lines until the next variable declaration or until the
next table row line.

A variable name must start with a letter and may consist of letters and
numbers. (i.e. ``/[a-z][a-z0-9]*/i``)

_code: Variables Example @lang<text>

\_table: Result of Variables Example

$Yes:    This option is supported.
$No:     This option is **not** supported
$bottom: This just represents an example of
         what is possible. Notice that variable
         content can span multiple lines.

|  **Feature**     |  **Supported**  |
|  Dancing Monkey  |      $Yes       |
|  Singing Turtle  |      $No        |
|  Newt Hair       |      $Yes       |
|        $bottom                    <|

_table: Result of Variables Example

$Yes: This option is supported.
$No:  This option is **not** supported.
$bottom: This just represents an example of
         what is possible. Notice that variable
         content can span multiple lines.

|  **Feature**     |  **Supported**  |
|  Dancing Monkey  |      $Yes       |
|  Singing Turtle  |      $No        |
|  Newt Hair       |      $Yes       |
|        $bottom                    <|


_subsection: Configuration @<flatworm-config>

Configuration is optional (but highly recommended) and may be either
a simple JSON file (config.json) or a JS file (config.js) placed in
the top  of the source folder.

TODO:  example JSON and example JS


_subsection: Extensions @<flatworm-extensions>

_heading: @inherit\< //markdown// >  @<flatworm--ext-inherit>

Adds an inherits description to a directive. The //markdown// may contain links.


_heading: @lang\< //text// >  @<flatworm--ext-lang>

Set the language a [code directive](flatworm--code) should be
syntax-highlighted for. If "javascript", the code will be evaluated.


_heading: @nav\< //text// >  @<flatworm--ext-nav>

Sets the name in the breadcrumbs when not the current node.


_heading: @note\<// markdown// >  @<flatworm--ext-note>

Adds a note to a directive. The //markdown// may contain links. If the directive
already has an @INHERIT extension, that will be used instead and the @NOTE will
be ignored.


_heading: @src\< //key// >  @<flatworm--ext-src>

Calls the configuration ``getSourceUrl(key, VALUE)`` to get a URL which
will be linked to by a link next to the //directive//.

This extended directive function requires an advanced ``config.js`` [[flatworm-config]]
file since it requires a JavaScript function.


_heading: @style\< //text// >  @<flatworm--ext-style>

The [Table Style](flatworm--table-style) to use for a table directive.