From eb44ce3eb922c90007311e17789010ef3b546fb5 Mon Sep 17 00:00:00 2001 From: Jonas Smedegaard Date: Wed, 1 Jul 2020 11:17:37 +0200 Subject: Initial draft --- spec.txt | 154 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 149 insertions(+), 5 deletions(-) diff --git a/spec.txt b/spec.txt index 7dcfc48..14c8d65 100644 --- a/spec.txt +++ b/spec.txt @@ -1,8 +1,8 @@ --- -title: CommonMark Spec -author: John MacFarlane -version: 0.29 -date: '2019-04-06' +title: CommonMark-RDF Spec +author: John MacFarlane & Jonas Smedegaard +version: 0.29.0alpha1 +date: '2020-06-30' license: '[CC-BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/)' ... @@ -3137,11 +3137,15 @@ consists of a [link label], optionally preceded by up to three spaces of indentation, followed by a colon (`:`), optional spaces or tabs (including up to one [line ending]), a [link destination], +an optional [annotation reference set], +which if it is present must be separated +from the [link destination] by spaces or tabs, optional spaces or tabs (including up to one [line ending]), and an optional [link title], which if it is present must be separated -from the [link destination] by spaces or tabs. +from the [link destination] and [annotation set] by spaces or tabs. No further character may occur. +If [annotation set] is present then [link destination] is optional. A [link reference definition] does not correspond to a structural element of a document. Instead, it @@ -3494,6 +3498,38 @@ no visible content: ```````````````````````````````` +## Annotation reference definitions + +An [annotation reference definition](@) +consists of an [annotation reference label], +optionally preceded by up to three spaces of indentation, +followed by a colon (`:`), +optional spaces or tabs (including up to one [line ending]), +an [annotation destination], +and an optional [annotation reference flag], +which if it is present must be separated +from the [annotation reference label] +and [annotation reference destination] +by spaces or tabs (including up to one [line ending]). +No further character may occur. +If [annotation reference flag] is present +then [annotation reference destination] is optional. + +An [annotation reference definition] +does not correspond to a structural element of a document. +Instead, it defines a label +which can be used in [annotations] elsewhere in the document. +[Annotation reference definitions] can come +either before or after the links that use them. + +FIXME: define [annotation reference label] + +FIXME: define [annotation reference flag] "@default" + +FIXME: define [annotation initial context] +from . + + ## Paragraphs A sequence of non-blank lines that cannot be interpreted as other @@ -8492,6 +8528,114 @@ is followed by a link label (even though `[bar]` is not defined):

[foo]bar

```````````````````````````````` +## Annotations + +An annotation contains [annotation text] (the visible text), and an [annotation set] +(the hints to annotate the text with). +There are six basic kinds of annotations in Markdown. +In [block annotations] the hints are given at the end of the block. +In [block-tree annotations] the hints are given +at the beginning of the topmost block. +In [block-siblings annotations] the hints are given +as a prototype sibling block immediately before the first sibling block. +In [block-cluster annotations] the hints are given +as a prototype parent block immediately before the first block in the cluster. +In [inline annotations] the hints are given +immediately after the link text. +In referenced annotations the hints are defined +in a [reference link] elsewhere in the document. + +An [annotation text](@) consists of either + +- a single explicitly enclosed inline element, + i.e. a [code span], + [emphasis or strong emphasis][emphasis and strong emphasis], + [link], [image], or [autolink], or + +- a sequence of zero or more inline elements + enclosed by square brackets (`[` and `]`). + +The following rules apply: + +- Annotations may not contain other annotations, at any level of nesting. + If multiple otherwise valid annotation definitions appear nested inside each + other, the inner-most definition is used. + +- Brackets are allowed in the [annotation text] only if (a) they + are backslash-escaped or (b) they appear as a matched pair of brackets, + with an open bracket `[`, a sequence of zero or more inlines, and + a close bracket `]`. + +- Backtick [code spans], [autolinks], and raw [HTML tags] bind more tightly + than the brackets in annotation text. Thus, for example, + `` [foo`]` `` could not be an annotation text, since the second `]` + is part of a code span. + +- The brackets in annotation text bind more tightly than markers for + [emphasis and strong emphasis]. Thus, for example, `*[foo*]{hint}` is a link. + +FIXME: define priority of link versus annotation text if necessary. + +An [annotation set](@) consists of a an opening `{`, +followed by optional spaces or tabs (including up to one [line ending]), +zero or more [annotation hints] +delimited by spaces or tabs (including up to one [line ending]), +optional spaces or tabs (including up to one [line ending]), +and a closing `}`. + +There are 3 types of [annotation hints][@] in Markdown. +[typeof hints], [property hints], and [resource hints]. + +A [typeof hint](@) consists of character `.`, +then an [annotation destination]. + +A [property hint](@) consists of an [annotation destination]. + +A [resource hint](@) consists of character `=`, +then an [annotation destination]. + +An [annotation destination](@) consists of either + +- a sequence of zero or more characters between an opening `<` and a + closing `>` that contains no line endings or unescaped + `<` or `>` characters, or + +- a nonempty sequence of characters that does not start with `<`, + does not include [ASCII control characters][ASCII control character] + or [space] character, and includes parentheses only if (a) they are + backslash-escaped or (b) they are part of a balanced pair of + unescaped parentheses. + (Implementations may impose limits on parentheses nesting to + avoid performance issues, but at least three levels of nesting + should be supported.) + +FIXME: tighten [annotation destination] to cover only <...> and CURIEs. + +FIXME: define [block annotation]. + +FIXME: define [block-tree annotation]. + +FIXME: define [block-siblings annotation]. + +FIXME: define [block-cluster annotation]. + +An [inline annotation](@) consists of an [annotation text] +followed immediately by an [annotation set]. + +The annotation consists of HTML tag attributes +with the type of [annotation hint] as key. +The annotation attribute's value is the [annotation destination], +excluding enclosing `<...>` if present. + +FIXME: define addition of prefix attributes +when deviating from [annotation initial context]. + +FIXME: define addition of vocab attribute +when declared in [annotation reference definition]. + +FIXME: define normalization of [annotation destination] into CURIE +based on [annotation initial context] +and prefixes in [annotation reference definitions]. ## Images -- cgit v1.2.3