From 14f6fb8462d6f030d3df774560fd3771556847b5 Mon Sep 17 00:00:00 2001
From: Jonas Smedegaard <dr@jones.dk>
Date: Wed, 1 Jul 2020 17:57:40 +0200
Subject: add annotated examples to link reference definitions

---
 spec.txt | 371 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 371 insertions(+)

diff --git a/spec.txt b/spec.txt
index 14c8d65..36459b0 100644
--- a/spec.txt
+++ b/spec.txt
@@ -3194,6 +3194,50 @@ them.
 ````````````````````````````````
 
 
+[Link reference definition] with [annotation hint]:
+
+```````````````````````````````` example
+[foo]: /url {.ex:hint} "title"
+
+[foo]
+.
+<p><a href="/url" typeof="ex:hint" title="title">foo</a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+   [foo]: 
+      /url  
+    {ex:hint}  
+           'the title'  
+
+[foo]
+.
+<p><a href="/url" property="ex:hint" title="the title">foo</a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+[Foo*bar\]]:my_(url) {=ex:hint} 'title (with parens)'
+
+[Foo*bar\]]
+.
+<p><a href="my_(url)" resource="ex:hint" title="title (with parens)">Foo*bar]</a></p>
+````````````````````````````````
+
+
+```````````````````````````````` example
+[Foo bar]:
+<my url>
+{.<my ødd iri>}
+'title'
+
+[Foo bar]
+.
+<p><a href="my%20ødd%20iri" typeof="µ%20iri" title="title">Foo bar</a></p>
+````````````````````````````````
+
+
 The title may extend over multiple lines:
 
 ```````````````````````````````` example
@@ -3228,6 +3272,35 @@ with blank line'
 ````````````````````````````````
 
 
+The annotation may extend over multiple lines:
+
+```````````````````````````````` example
+[foo]: /url {
+.ex:first
+=ex:second
+}
+
+[foo]
+.
+<p><a href="/url" typeof="ex:first" property="ex:second">foo</a></p>
+````````````````````````````````
+
+
+However, it may not contain a [blank line]:
+
+```````````````````````````````` example
+[foo]: /url {.ex:hint
+
+=ex:hint_after_blank_line}
+
+[foo]
+.
+<p>[foo]: /url {.ex:hint</p>
+<p>=ex:hint_after_blank_line}</p>
+<p>[foo]</p>
+````````````````````````````````
+
+
 The title may be omitted:
 
 ```````````````````````````````` example
@@ -3262,6 +3335,41 @@ The link destination may not be omitted:
 <p><a href="">foo</a></p>
 ````````````````````````````````
 
+The link destination may be omitted
+when an annotation is included:
+
+```````````````````````````````` example
+[foo]: {.ex:hint}
+
+[foo]
+.
+<p><div typeof="ex:hint">foo</div></p>
+````````````````````````````````
+
+
+An empty [annotation destination] may be specified
+using angle brackets:
+
+```````````````````````````````` example
+[foo]: {<>}
+
+[foo]
+.
+<p><div resource="">foo</div></p>
+````````````````````````````````
+
+An empty [annotation destination] as CURIE is not allowed, however:
+
+```````````````````````````````` example
+[foo]: {.}
+
+[foo]
+.
+<p>[foo]: {.}</p>
+<p>[foo]</p>
+````````````````````````````````
+
+
 The title must be separated from the link destination by
 spaces or tabs:
 
@@ -3275,6 +3383,28 @@ spaces or tabs:
 ````````````````````````````````
 
 
+The annotation must be separated from the link destination by
+spaces or tabs
+
+```````````````````````````````` example
+[foo]: <bar>{.ex:hint}
+
+[foo]
+.
+<p>[foo]: <a typeof="ex:hint" href="bar">bar</a></p>
+<p>[foo]</p>
+````````````````````````````````
+
+```````````````````````````````` example
+[foo]: /bar{.ex:hint}
+
+[foo]
+.
+<p>[foo]: /bar{.ex:hint}</p>
+<p>[foo]</p>
+````````````````````````````````
+
+
 Both title and destination can contain backslash escapes
 and literal backslashes:
 
@@ -3287,6 +3417,30 @@ and literal backslashes:
 ````````````````````````````````
 
 
+Annotation can contain backslash escapes
+in angle brackets:
+
+```````````````````````````````` example
+[foo]: /url\bar\*baz {.<foo\"bar\baz>}
+
+[foo]
+.
+<p><a href="/url%5Cbar*baz" typeof="foo&quot;bar\baz">foo</a></p>
+````````````````````````````````
+
+Annotation cannot contain backslash escapes
+in CURIE form, however:
+
+```````````````````````````````` example
+[foo]: /url\bar\*baz {.ex:foo\"bar\baz}
+
+[foo]
+.
+<p>[foo]: /url\bar\*baz {.ex:foo\"bar\baz}</p>
+<p>[foo]</p>
+````````````````````````````````
+
+
 A link can come before its corresponding definition:
 
 ```````````````````````````````` example
@@ -3297,6 +3451,16 @@ A link can come before its corresponding definition:
 <p><a href="url">foo</a></p>
 ````````````````````````````````
 
+```````````````````````````````` example
+[foo]
+
+[foo]: url {.ex:hint}
+.
+<p><a href="url" typeof="ex:hint">foo</a></p>
+````````````````````````````````
+
+
+
 
 If there are several matching definitions, the first one takes
 precedence:
@@ -3310,6 +3474,54 @@ precedence:
 <p><a href="first">foo</a></p>
 ````````````````````````````````
 
+```````````````````````````````` example
+[foo]
+
+[foo]: url {.ex:first}
+[foo]: url {.ex:second}
+.
+<p><a href="url" typeof"ex:first">foo</a></p>
+````````````````````````````````
+
+```````````````````````````````` example
+[foo]
+
+[foo]: url {.ex:first}
+[foo]: url {=ex:second}
+.
+<p><a href="url" typeof"ex:first">foo</a></p>
+````````````````````````````````
+
+```````````````````````````````` example
+[foo]: url {.ex:first}
+
+[foo]
+
+[foo]: url {=ex:second}
+.
+<p><a href="url" typeof"ex:first">foo</a></p>
+````````````````````````````````
+
+```````````````````````````````` example
+[foo]
+
+[foo]: url {}
+
+[foo]: url {=ex:second}
+.
+<p><a href="url">foo</a></p>
+````````````````````````````````
+
+```````````````````````````````` example
+[foo]
+
+[foo]: url
+
+[foo]: url {=ex:second}
+.
+<p><a href="url">foo</a></p>
+````````````````````````````````
+
 
 As noted in the section on [Links], matching of labels is
 case-insensitive (see [matches]).
@@ -3322,6 +3534,13 @@ case-insensitive (see [matches]).
 <p><a href="/url">Foo</a></p>
 ````````````````````````````````
 
+```````````````````````````````` example
+[FOO]: /url {.ex:hint}
+
+[Foo]
+.
+<p><a href="/url" typeof="ex:hint">Foo</a></p>
+````````````````````````````````
 
 ```````````````````````````````` example
 [ΑΓΩ]: /φου
@@ -3331,6 +3550,14 @@ case-insensitive (see [matches]).
 <p><a href="/%CF%86%CE%BF%CF%85">αγω</a></p>
 ````````````````````````````````
 
+```````````````````````````````` example
+[ΑΓΩ]: /φου {.φου:φου φου:φου =φου:φου .<φου> <φου> =<φου>}
+
+[αγω]
+.
+<p><a href="/%CF%86%CE%BF%CF%85" typeof="φου:φου φου" resource="φου:φου φου" property="φου:φου φου">αγω</a></p>
+````````````````````````````````
+
 
 Here is a link reference definition with no corresponding link.
 It contributes nothing to the document.
@@ -3353,6 +3580,26 @@ bar
 ````````````````````````````````
 
 
+Here are some with annotation:
+
+```````````````````````````````` example
+[foo]: /url {.ex:hint}
+.
+````````````````````````````````
+
+```````````````````````````````` example
+[
+foo
+]: /url
+{
+.ex:hint
+}
+bar
+.
+<p>bar</p>
+````````````````````````````````
+
+
 This is not a link reference definition, because there are
 characters other than spaces or tabs after the title:
 
@@ -3361,6 +3608,22 @@ characters other than spaces or tabs after the title:
 .
 <p>[foo]: /url &quot;title&quot; ok</p>
 ````````````````````````````````
+Here is a bogus annotated one with stuff after title:
+
+```````````````````````````````` example
+[foo]: /url {.ex:hint} "title" ok
+.
+<p>[foo]: /url {.ex:hint} &quot;title&quot; ok</p>
+````````````````````````````````
+
+This is not a link reference definition,
+because there are characters other than spaces or tabs or title after annotation:
+
+```````````````````````````````` example
+[foo]: /url {.ex:hint} ok
+.
+<p>[foo]: /url {.ex:hint} ok</p>
+````````````````````````````````
 
 
 This is a link reference definition, but it has no title:
@@ -3372,6 +3635,16 @@ This is a link reference definition, but it has no title:
 <p>&quot;title&quot; ok</p>
 ````````````````````````````````
 
+Here is an annotated link reference definition, without title:
+
+```````````````````````````````` example
+[foo]: /url {.ex:hint}
+"title" ok
+.
+<p>&quot;title&quot; ok</p>
+````````````````````````````````
+
+
 
 This is not a link reference definition, because it is indented
 four spaces:
@@ -3385,6 +3658,17 @@ four spaces:
 </code></pre>
 <p>[foo]</p>
 ````````````````````````````````
+Here is a bogus one indented four spaces, with annotation:
+
+```````````````````````````````` example
+    [foo]: /url {.ex:hint} "title"
+
+[foo]
+.
+<pre><code>[foo]: /url {.ex:hint} &quot;title&quot;
+</code></pre>
+<p>[foo]</p>
+````````````````````````````````
 
 
 This is not a link reference definition, because it occurs inside
@@ -3402,6 +3686,21 @@ a code block:
 <p>[foo]</p>
 ````````````````````````````````
 
+Here is an annotated bogus link reference definition in code block:
+
+```````````````````````````````` example
+```
+[foo]: /url {.ex:hint}
+```
+
+[foo]
+.
+<pre><code>[foo]: /url {.ex:hint}
+</code></pre>
+<p>[foo]</p>
+````````````````````````````````
+
+
 
 A [link reference definition] cannot interrupt a paragraph.
 
@@ -3416,6 +3715,17 @@ Foo
 <p>[bar]</p>
 ````````````````````````````````
 
+```````````````````````````````` example
+Foo
+[bar]: /baz {.ex:hint}
+
+[bar]
+.
+<p>Foo
+[bar]: /baz {.ex:hint}</p>
+<p>[bar]</p>
+````````````````````````````````
+
 
 However, it can directly follow other block elements, such as headings
 and thematic breaks, and it need not be followed by a blank line.
@@ -3431,6 +3741,17 @@ and thematic breaks, and it need not be followed by a blank line.
 </blockquote>
 ````````````````````````````````
 
+```````````````````````````````` example
+# [Foo]
+[foo]: /url {.ex:hint}
+> bar
+.
+<h1><a href="/url" typeof="ex:hint">Foo</a></h1>
+<blockquote>
+<p>bar</p>
+</blockquote>
+````````````````````````````````
+
 ```````````````````````````````` example
 [foo]: /url
 bar
@@ -3441,6 +3762,16 @@ bar
 <p><a href="/url">foo</a></p>
 ````````````````````````````````
 
+```````````````````````````````` example
+[foo]: /url {.ex:hint}
+bar
+===
+[foo]
+.
+<h1>bar</h1>
+<p><a href="/url" typeof="ex:hint">foo</a></p>
+````````````````````````````````
+
 ```````````````````````````````` example
 [foo]: /url
 ===
@@ -3450,6 +3781,15 @@ bar
 <a href="/url">foo</a></p>
 ````````````````````````````````
 
+```````````````````````````````` example
+[foo]: /url {.ex:hint}
+===
+[foo]
+.
+<p>===
+<a href="/url" typeof="ex:hint">foo</a></p>
+````````````````````````````````
+
 
 Several [link reference definitions]
 can occur one after another, without intervening blank lines.
@@ -3469,6 +3809,22 @@ can occur one after another, without intervening blank lines.
 <a href="/baz-url">baz</a></p>
 ````````````````````````````````
 
+```````````````````````````````` example
+[foo]: /foo-url {.ex:first} "foo"
+[bar]: /bar-url
+{.ex:second}
+  "bar"
+[baz]: /baz-url {.ex:third}
+
+[foo],
+[bar],
+[baz]
+.
+<p><a href="/foo-url" typeof="ex:first" title="foo">foo</a>,
+<a href="/bar-url" typeof="ex:second" title="bar">bar</a>,
+<a href="/baz-url" typeof="ex:third">baz</a></p>
+````````````````````````````````
+
 
 [Link reference definitions] can occur
 inside block containers, like lists and block quotations.  They
@@ -3485,6 +3841,16 @@ are defined:
 </blockquote>
 ````````````````````````````````
 
+```````````````````````````````` example
+[foo]
+
+> [foo]: /url {.ex:hint}
+.
+<p><a href="/url" typeof="ex:hint">foo</a></p>
+<blockquote>
+</blockquote>
+````````````````````````````````
+
 
 Whether something is a [link reference definition] is
 independent of whether the link reference it defines is
@@ -3497,6 +3863,11 @@ no visible content:
 .
 ````````````````````````````````
 
+```````````````````````````````` example
+[foo]: /url {.ex:hint}
+.
+````````````````````````````````
+
 
 ## Annotation reference definitions
 
-- 
cgit v1.2.3