diff options
Diffstat (limited to 'cnm-specification.cnm')
| -rw-r--r-- | cnm-specification.cnm | 192 |
1 files changed, 190 insertions, 2 deletions
diff --git a/cnm-specification.cnm b/cnm-specification.cnm index c599a61..73c65e5 100644 --- a/cnm-specification.cnm +++ b/cnm-specification.cnm @@ -1,5 +1,5 @@ title - ContNet Markup specification, version 0.4 draft (2017-09-01) + ContNet Markup specification, version 0.4 (2017-09-04) content section Overview @@ -430,7 +430,7 @@ content text fmt The ``embed`` block is used to embed external content into the document. - The first block argument represents the MIME type of the embedded content. It can be used by the user agent to decide how to handle it. Graphical browsers are recommended to display at least common image types (e.g. ``image/png``, ``image/jpeg``, ``image/webp`` and ``image/svg``) inside the page by default. An empty argument or invalid MIME type can be treated as an application/octet-stream type and not be embedded. + The first block argument represents the MIME type of the embedded content. It can be used by the user agent to decide how to handle it. Graphical browsers are recommended to display at least common image types (e.g. ``image/png``, ``image/jpeg``, ``image/webp`` and ``image/svg+xml``) inside the page by default. An empty argument or invalid MIME type can be treated as an application/octet-stream type and not be embedded. The second argument is the URL pointing to the embedded content. An embed block without a URL should be ignored. The URL may also be a data URI. @@ -450,6 +450,194 @@ content __**TL;DR:** Argument is MIME type and URL, contents are description. Embed inside page if possible, otherwise provide hyperlink. + section Selectors + text fmt + CNM selector queries can be used to identify specific sections in a CNM document. + + Selectors can be used to select a section in the document (e.g. to move an open document so that it's visible) or filter a document to only show certain sections and their content. The former + + + section Section selector + text fmt + A section selector query identifies a specific section in the document. It's usually used in the hash fragment part of a URL to move the visible document to the named section. Section title selectors are case-sensitive. + + Section selectors can select sections either by a section title, a path of section titles or a path of section indices. A section without a title does not count as a section and cannot be selected by section selectors; any mention of sections in the specification of selectors refers exclusively to sections with non-empty titles. A section with an empty title can essentially be regarded as a generic container block. + + section Title selector + raw + #{title} + + text fmt + The title selector selects the first section with the given title (``{title}``) in the document. The section order is defined by their vertical position; block depth is irrelevant. If multiple sections in the document have the same title, this selector only selects the first one. The title must use URL percent-encoding where at least the slash character (``U+002F``) is encoded into ``%2F`` or ``%2f``. + + An empty title matches the top of the document contents. + + Note that the ``#`` character (``U+0023``) in the selector is not the same as the one separating the URL hash fragment. An example URL with a title selector is @@cnp://example.com/file.cnm##title@@. + + section Title path selector + raw + /{path} + + text fmt + The title path selector selects a section based on a path of section titles. The ``{path}`` part of the query consists of zero or more section titles (escaped just like in the title selector) separated by a single slash character. + + Each title in the path selects a section using the same method as the title selector, but only considers sections that aren't a child block of another section in the current context (are accessible from the current context without passing through another section). The initial context is the top-level ``content`` block. Each time a section in the path is matched, the new context becomes this section's contents. + + If any part of the path fails to find a matching section, the query does not match anything. + + An empty path matches the top of the document contents. An empty title in a non-empty path does not match anything. + + section Index path selector + raw + ${indices} + + text fmt + The index path selector selects a section based on a path of section indices. The ``{indices}`` part of the query is a dot-separated path of zero or more section indices represented by decimal numbers. + + Each index in the path selects a section within the current context (as in the title path selector). The first section has the index 1. + + If any index in the path is zero or higher than the number of the sections in its context, the query does not match anything. + + An empty path matches the top of the document contents. + + + section Content selector + text fmt + A content selector is a selector that selects a subset of the document contents based on a section. + + The content selectors have the same syntax as the section selectors, but may be optionally prefixed with an exclamation mark (``U+0021``) for a shallow selector. + + Using a content selector query on a document returns a new document consisting of only the named section, all of its contents and all parent block names up to the top-level without any of their sibling blocks or other contents. + + A shallow selector selects a similar document, but excludes the contents of any child sections of the selected section (the section block name lines and any non-section blocks with their contents are kept). + + For the cases where a specific selector selects the top of the document contents, the entire ``content`` block with all of its contents is selected (or, in the case of a shallow selector, without child section contents). + + An empty content selector selects the entire document with all of its contents, including non-``content`` top-level blocks, unmodified (though the actual document may be recomposed, as long as the contents aren't changed). A content selector consisting only of the shallow selector modifier ``!`` selects the same document, but without the contents of any sections. + + + section Examples + text fmt + Example CNM document: + + raw text/cnm + title + Test + content + section A + text + T1 + section B + text + T2 + list + text + T3 + section C + text + T4 + section C + text + T5 + list + section + text + T6 + section E + text + T7 + text + T8 + section E + text + T9 + + text fmt + Section selectors: + list + text fmt + ``#A`` selects the section ""A"" containing the text ""T1"", section ""B"" and section ""C"". + text fmt + ``#C`` selects the section ""C"" containing the text ""T4"". + text fmt + ``#F`` does not select anything. + text fmt + ``/A`` selects the section ""A"" containing the text ""T1"", section ""B"" and section ""C"". + text fmt + ``/A/B/C`` selects the section ""C"" containing the text ""T4"". + text fmt + ``/A/C`` selects the section ""C"" containing the text ""T5"". + text fmt + ``/E`` selects the section ""E"" containing the text ""T7"". + text fmt + ``/B`` does not select anything. + text fmt + ``$1`` selects the section ""A"" containing the text ""T1"", section ""B"" and section ""C"". + text fmt + ``$2`` selects the section ""E"" containing the text ""T7"". + text fmt + ``$3`` selects the section ""E"" containing the text ""T9"". + text fmt + ``$1.1.1`` selects the section ""C"" containing the text ""T4"". + text fmt + ``$1.3`` does not select anything. + + text fmt + Content selectors: + list + section + text fmt + ``#C`` selects the following document: + raw text/cnm + content + section A + section B + list + section C + text + T4 + section + text fmt + ``!/A`` selects the following document: + raw text/cnm + content + section A + text + T1 + section B + section C + section + text fmt + ``!/`` selects the following document: + raw text/cnm + content + section A + list + section + text + T6 + section E + text + T8 + section E + section + text fmt + ``!`` selects the following document: + raw text/cnm + title + Test + content + section A + list + section + text + T6 + section E + text + T8 + section E + + section The CNMfmt inline formatting submarkup text fmt The CNMfmt markup is used within ``text fmt`` content blocks to provide inline formatting of text. |