diff options
| -rw-r--r-- | cnm-specification.cnm | 169 |
1 files changed, 169 insertions, 0 deletions
diff --git a/cnm-specification.cnm b/cnm-specification.cnm new file mode 100644 index 0000000..8808481 --- /dev/null +++ b/cnm-specification.cnm @@ -0,0 +1,169 @@ +title + CNM 0.1 + +content + text fmt + This is an archived copy of the original draft of the ContNet Markup from 2013. It has never been implemented and contains numerous flaws. + + raw text/cnm + title + Title goes here + + links + http://whatever.com/ Whatever.com on HTTP + cnp://something.net/else/ + ../another-link + + site + page1 Page 1 + another-page Just Another Page + test This maps to /test + foo and this to /test/foo + bar.txt this is /test/foo/bar.txt file + baz.jpg again in /test/foo/baz.jpg + quux + qwe the above page is shown as "quux" + + references + cnp://this.is/a/reference ref1 Explanation of the reference + /some/file ref2 + + content + section The format + This is the ContNet content format. It is designed to be easy to write and parse, + as well as to be readable without any formatting. + + section Features + list + - simple to parse by computers + - simple to generate with scripts + - easy to write manually + - raw documents are readable + - no layout definitions, only content + - sections + - lists + - [[/some/page/ links]] + - [[@ref1 references]] + - [[#Features section references]] + - UTF-8 with LF newlines + + section Layout + The document is split into several blocks. + + Each block is indented by a tab character. The block lasts until the first + line that contains something besides tabs that has lesser or equal + indentation to the block declaration. Indenting a block with more than one + tab is an error. Blank lines can be indented or not and will act the same + (end the paragraph). + + A block declaration is the line after which a new indentation level is added. + + section Top level blocks + The outtermost block can contain only the top-level blocks and these can + only appear in that block: + list + - title: The page title, a single string (optionally even multiline). + - links: A list of URLs and paths that can point to anywhere. + These could be displayed in, for example, the top menu below the title. + - site: A map of the current website. Consists of the basename of the file + or folder optionally followed by a name to show instead of the filename. + Each entry can have other entries nested. + - references: A list of URLs and paths with identifiers. These can be + later referenced in the link context with the identifier prefixed by the @ + character. When used without link text, references could be rendered as, + for example, Wikipedia-style [1] references. The reference's URL can be + #, the empty bookmark, if the reference doesn't contain a link. + - content: Contains the main section of the page. The top level of content + can contain only sections. + + Multiple top-level blocks of the same type are concatenated together as if + they were one block. This may be undesirable for the title block, as it will + add a newline. + + section Content blocks + list + - section: Optionally named section of the content. Can be nested in other + sections. This is the only block that can be on the top level. If a name + is provided, it is displayed as the section title and can be referenced + as an in-page bookmark in the link context using the name identifier + prefixed with the # character. A section is a generic container for other + blocks or text. + - table: Defines a table. The first line in the table defines the table + header, the rest are cells. Columns are prefixed with the | character. + Each row ends in a newline. To omit the header, leave its cells blank. + The number of columns in the table is equal to the longest row's. If a + line does not begin with |, it's considered to be a continuation of the + previous row's last cell. That way, multi-paragraph cells are possible. + - code: All text inside this block is displayed as it is, without any + parsing being done. This includes additional indents. Optionally, the + language can be specified as a parameter to the block definition, so that + a client that supports syntax highlighting can format that code. The + language name should be the lowercase primary filename extension for a file + containing such source code, such as "c", "js", "cpp", "cob" and "cl". + - list: An unordered list. Each item starts with a - on the start of a + line and lasts until the next item or the end of the list block. Each + list item acts as a section, so it's possible to nest blocks in them. + + section Paragraphs + A paragraph is text that is not a block. It lasts until a blank line, the + end of the current block or the start of a new block. The lines within a + paragraph will be joined with spaces. Paragraphs can be in any text + context, such as in list items, table cells, link text, etc. + + section Text + Text appears within paragraph. It should be UTF-8 encoded. It can contain + any characters that are not part of the syntax. Notably, the only + characters that can't be included by escaping are tabs on start of a line + and the newline character. Whitespace is collapsed. + + Text can be bold (toggle with \*\*) and italic (\_\_). Once toggled, the + style will last until it is toggled again or the end of the paragraph. + + section Tables + This format supports tables: + + table + | column1 | column2 + | row | 1 + | row | 2 + + section Links + A link can be added inline using the link context: + + code + [[path text to display]] + + The "path" can be an URL or a CNP relative or absolute path, as well as + a reference when prefixed with @ and a bookmark when prefixed with #. + + "text to display" is the text to which the link is added. If omitted or + blank, the path will be shown. + + section Escaping + URLs, both cnp:// and others, have to be escaped using the standard URL + escaping. + + CNP paths have to be escaped just like in the ContNet protocol: + table + | character | escape sequence + | space | \\_ + | newline | \\n + | NUL | \\0 + | backslash | \\\\ + + Various parts of the syntax can be escaped too: + table + | character | escape sequence + | table \| | \\| + | list - | \\- + | asterisk | \\* + | underscore | \\_ + | link \[ | \\\[ + | link \] | \\\] + | backslash | \\\\ + + section TODO + list + - Embedded content + - Metadata + - TODO |