summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--cnm-specification.cnm169
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