From 12c11df9bb748ca71f125eabf65e6a20e9c5ac2f Mon Sep 17 00:00:00 2001
From: dhh1128 <daniel.hardman@gmail.com>
Date: Fri, 8 Jul 2022 11:59:01 +0200
Subject: [PATCH] various bits of progress

Signed-off-by: dhh1128 <daniel.hardman@gmail.com>
---
 docs/spec/README.md                |   8 +--
 docs/spec/asides.md                |  33 +++++++++
 docs/spec/highlights.md            |  18 +++++
 docs/spec/hypertext-state.md       |  14 ++++
 docs/spec/hypertext.md             | 104 +++++++++++++----------------
 docs/spec/metadata.md              |  24 +++++++
 docs/spec/tables.md                |  34 ++++++++++
 docs/tests/autolinks.html          |   3 +
 docs/tests/autolinks.i             |   3 +
 docs/tests/contrived messy ID.html |   1 +
 docs/tests/contrived messy ID.i    |   1 +
 docs/tests/normal hyperlink.html   |   1 +
 docs/tests/normal hyperlink.i      |   1 +
 docs/tests/terse hyperlink.html    |   1 +
 docs/tests/terse hyperlink.i       |   1 +
 15 files changed, 186 insertions(+), 61 deletions(-)
 create mode 100644 docs/spec/asides.md
 create mode 100644 docs/spec/highlights.md
 create mode 100644 docs/spec/hypertext-state.md
 create mode 100644 docs/spec/metadata.md
 create mode 100644 docs/spec/tables.md
 create mode 100644 docs/tests/autolinks.html
 create mode 100644 docs/tests/autolinks.i
 create mode 100644 docs/tests/contrived messy ID.html
 create mode 100644 docs/tests/contrived messy ID.i
 create mode 100644 docs/tests/normal hyperlink.html
 create mode 100644 docs/tests/normal hyperlink.i
 create mode 100644 docs/tests/terse hyperlink.html
 create mode 100644 docs/tests/terse hyperlink.i

diff --git a/docs/spec/README.md b/docs/spec/README.md
index f880691a..0bf7320a 100644
--- a/docs/spec/README.md
+++ b/docs/spec/README.md
@@ -13,15 +13,13 @@ Note which audience member is listed first. One of the goals of intent is to kee
 
 ### IML
 
-IML is a variation of [Github-Flavored Markdown](https://github.github.com/gfm/) (which is in turn a variation of [CommonMark](https://spec.commonmark.org/)). Rather than reproducing a slight variation on the GFM spec here, only differences are documented.
+IML is a variation of [Github-Flavored Markdown](https://github.github.com/gfm/) (which is in turn a variation of [CommonMark](https://spec.commonmark.org/)). Rather than reproducing a slight variation on the GFM spec here, intent's documentation of IML emphasizes just the differences.
 
 #### Different assumptions
 
-Markdown prioritizes the goal of generating content that can display safely inside a containing website. This means it favors simple syntax, even at the expense of expressive power. Typically, implementations also sanitize various HTML constructs (CSS, `<style>`, `<script>`, many HTML tag attributes, etc.) to prevent [cross-site scripting (XSS)](https://owasp.org/www-community/attacks/xss/#) and [scriptless attacks](https://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.469.7647&rep=rep1&type=pdf). 
+Markdown (a *writing* format) prioritizes the goal of writing content that is readable as plaintext, and transforming it into HTML (a *publishing* format) that can display safely inside a containing website. This means it [favors simple syntax and advocates using inline HTML for advanced constructs](https://daringfireball.net/projects/markdown/syntax#html). But typically, implementations also sanitize various HTML constructs (CSS, `<style>`, `<script>`, many HTML tag attributes, etc.) to prevent [cross-site scripting (XSS)](https://owasp.org/www-community/attacks/xss/#) and [scriptless attacks](https://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.469.7647&rep=rep1&type=pdf); this means markdown is linmited as a basis for fancy documents.
 
-Markdown makes no attempt to expand HTML's expressive power; the output of a markdown transform is a strict subset of what HTML is capable of representing.
-
-IML prioritizes powerful standalone documents more highly. Although most IML is as simple to learn and read as markdown, it has more options for advanced users. And instead of mandating the sanitization of dangerous HTML elements, it defines choices for [transforming](../glossary.html#iml-transformation) in [embeddable mode](../glossary.html#embeddable-mode), [standalone mode](../glossary.html#standalone-mode), or [natural mode](../glossary.html#natural-mode). This preserves safety where it is needed, but allows far more sophisticated standalone output.
+IML is still a *writing* format, like markdown; it also renders to HTML for publication. However, it prioritizes expressive power and standalone documents more highly. Although most IML is as simple to learn and read as markdown, it has more options for advanced users. And instead of mandating the sanitization of dangerous HTML elements, it defines choices for [transforming](../glossary.html#iml-transformation) in [embeddable mode](../glossary.html#embeddable-mode), [standalone mode](../glossary.html#standalone-mode), or [natural mode](../glossary.html#natural-mode). This preserves safety where it is needed, but allows more nuanced output.
 
 IML also introduces some semantics that extend beyond the limits of ordinary HTML.
 
diff --git a/docs/spec/asides.md b/docs/spec/asides.md
new file mode 100644
index 00000000..e934d886
--- /dev/null
+++ b/docs/spec/asides.md
@@ -0,0 +1,33 @@
+# Asides
+
+An __aside__ is a piece of content that is related to but separate from the main flow of a document. In an editor, asides are defined inline: inside, next to, or near the content they enhance. However, they may render in an entirely different place such as a footer or an appendix. Intent uses asides for things like footnotes, endnotes, and callouts. 
+
+An aside has one or more __display points__ where its content or some subset or transformation thereof is rendered.
+
+A display point for an aside is defined with an expression in the form `[^@id: anchor content]`, where `id` is a formal identifier for the interjection.
+
+The aside content (e.g., the text of a footnote, the diagram) is defined at a __definition point__. This may be an anchor in the form `[^id: aside content]`, or a formally named block that has a type, marks, and other properties. In the latter case, the block should carry the `+aside` mark to indicate that it is not to be displayed as part of the running context.
+
+Suppose you are using intent to write about some product requirements, and you want to add a footnote about accessibility. You might do it like this:
+
+```i
+We need to make sure that we consider accessibility. Some of our
+customers [^@1: say] that they won't buy unless the product is
+usable by the visually impaired.
+
+[^1: See the focus group done in Sep 2019.]
+```
+
+You could also do it like this:
+
+```i
+We need to make sure that we consider accessibility. Some of our
+customers [^@1: say] that they won't buy unless the product is
+usable by the visually impaired.
+
+^1: footnote
+    See the focus group done in Sep 2019.
+```
+
+
+
diff --git a/docs/spec/highlights.md b/docs/spec/highlights.md
new file mode 100644
index 00000000..febadca6
--- /dev/null
+++ b/docs/spec/highlights.md
@@ -0,0 +1,18 @@
+# Highlights
+
+Highlights are intent's way of adding visual overlays to text,[^1] much as markers or colored pencils can mark up paper documents. Highlights may be used for scholarly analysis, feedback, or meta commentary.
+
+Highlights can be added to an intent document by original authors and by subsequent readers. Highlights are organized into layers, and individual layers can be shown or hidden.
+
+Highlights are visualized with subtle color and lines, and exhibit helpful behaviors on mouse-over and click events. This allows semantic richness without overwhelming the text itself. However, it introduces a challenge: in modern browsers and editors, color and layout are influenced by many external factors such as light/dark theme, accessibility settings, and screen resolution. Therefore, the creator of a highlight gives only hints about its appearance (e.g., a base color and style); exact rendering is reserved for code that tweaks alpha channel and other characteristics to suit the circumstances. 
+
+{
+[1]: Conceptually, intent highlights resemble a `<span>` in HTML; the goal is to paint a region of text with additional semantics. However, the correspondence is not perfect. As their name implies, intent highlights are always intended to create a visual effect; HTML `<span>` tags may have a non-visual purpose.
+}
+
+effect | rendering | syntax
+--- | --- | ---
+marker highlight | Apply a background color to text; intensify the color on hover. | `[~ marked text]` for default orange (`#ffa500`). Colors can also be named: `[~red~ marked text]` or specified by 3-char RGB triple: `[~808~ marked text]` (for purple). Note that colors are used as the basis of the visual effect, but are not rendered exactly as given; their alpha channel is adjusted.
+box highlight | A lightly visible (mostly transparent) bounding rectangle is drawn. Color of the rectangle, and all other rectangles with the same appearance, intensifies on hover. | <code>[&vert; boxed text]</code> for gray. Colors can also be named or specified by 3-char RGB triple: <code>[&vert;blue&vert; text]</code> or <code>[&vert;e93&vert; text]</code> (for orange)
+underline highlight | A lightly visible (mostly transparent) underline is drawn; this is different from a simple html `<u>` in that the underline does not have the same color as the text. Color of the underline, and all other underlines with the same appearance, intensifies on hover. | `[_ underlined text]` for gray.
+placeholder highlight | A dotted box, lightly shaded, is created to show that something is missing.
diff --git a/docs/spec/hypertext-state.md b/docs/spec/hypertext-state.md
new file mode 100644
index 00000000..a7afe1f3
--- /dev/null
+++ b/docs/spec/hypertext-state.md
@@ -0,0 +1,14 @@
+State machine for parsing hypertext
+
+&nbsp; | [ | [+ | [= | [# | : | \] | @ | other | EOL
+ --- | --- | --- | --- | --- | --- | --- | --- | --- | ---
+(null) | push in-hyper | push need-id | push in-def | push in-terse | no change | no change | no change | no change | no change
+in-hyper (hypertext of unknown type) | push in-hyper | push need-id | push in-def | push in-terse | no change | goto in-empty (might have ID) | goto in-link | goto in-anchor | E1: expected ] x recursed layers
+need-id | E2: can't put hypertext here | E2 | E2 | E2 | E3: expected ID | E3 | E3 | goto need-colon | E3 + E1
+need-colon | E2 | E2 | E2 | E2 | goto in-hyper | E4: expected colon | E4 | no change | E4 + E3 + E1
+in-anchor | push in-hyper | push need-id | push in-def | push in-terse | no change | save ID; pop | no change | no change | E1
+in-def | push in-hyper | push need-id | push in-def | push in-terse | no change | save ID; pop | no change | no change | E1
+in-terse | push in-hyper | push need-id | push in-def | push in-terse | no change | save ref; pop | no change | no change | E1
+in-empty | E5: useless empty; pop; push in-hyper | E5; pop; push need-id | E5; pop; push in-def | E5; pop; push in-terse | E5; pop | E5; pop | E5; pop | if ( goto show-raw else E5; pop | E5
+in-link | need special handling of ; and x=y for params
+
diff --git a/docs/spec/hypertext.md b/docs/spec/hypertext.md
index 340dcfd6..fad4686d 100644
--- a/docs/spec/hypertext.md
+++ b/docs/spec/hypertext.md
@@ -1,22 +1,31 @@
+asides with {} on line by itself, outdented; possibly identify or stylize the asides after opening bracket
+special convention: single letter ids resets with every paragraph (not a disjoint anchor)
+spans: not for hyperlinking but for connecting, underlining, etc: [- highlighted text] or [_ underlined text] or [| boxed text] (default color = gray); also [-red- text] or [_red_ text] or [|red| text]
+footnotes with [#a: referencing text] and [a:] explanatory note
+multiple footnotes on the same referencing text: [#a,b: referencing text]
+paragraph numbers with 1- instead of 1.
+autonumber list/paragraph with 0. and 0-; otherwise manually numbered
+list styles a.
+
 ## Hypertext
 
-Intent is an extremely powerful hypertext format. For clarity and ease of use, it supports most hypertext features from markdown. It also plugs gaps where markdown can't quite match HTML (e.g., the ability to specify a `target` for a link). And it even goes beyond HTML, offering asides, comments, and footnotes/endnotes like a word processor, definition links like ReSpec, and a few hypertext constructs that are totally unique.
+Intent is an extremely powerful hypertext format. For clarity and ease of use, it supports most hypertext features from pure markdown and from [many of markdown's variants](https://gist.github.com/vimtaai/99f8c89e7d3d02a362117284684baa0f). It also plugs gaps where markdown omits an HTML feature (e.g., the ability to specify a `target` for a link). And it even goes beyond HTML, offering [highlights](highlights.md), [comments, footnotes, and endnotes](asides.md) like a word processor, [definition links like ReSpec](https://respec.org/docs/#definitions-and-linking), plus a few hypertext constructs that are totally unique.
 
 ### Quick Reference
 
 element | syntax
 --- | ---
-[normal hyperlink](#hyperlinks) | `[clickable content](ref)`, as in markdown. Advanced params can be added after `ref` using <code>&vert;</code> and `target=x; rel=y` syntax. Unlike HTML or markdown, IML allows nested anchors (e.g., where a full sentence is an anchor, a word inside the sentence can also be an anchor).
+[normal hyperlink](#hyperlinks) | `[clickable content](ref)`, as in markdown. Advanced params can be added after `ref` but before the closing paren, using <code>&vert;</code> and `a=b; x=y` syntax: <code>[clickable content](ref&vert; download=license.txt; rel=license)</code>. Whitespace before and after the <code>&vert;</code> and `;` characters are optional.
 [terse hyperlink](#terse-hyperlinks) | `[#clickable content]`, where the clickable content [derives the ID](#comparing-anchor-ids) of an anchor elsewhere. The `#` character is not rendered.
-autolinks | Tokens that match URI syntax and that begin with `http://`, `https://`, and `mailto:` are automatically treated as hyperlinks by intent, unless they are immediately preceded by empty braces, as in `[]http://example.com/dont-make-me-clickable`.
-[simple text anchor](#simple-text-anchors) | `[anchor text]`. ID is [derived from](#comparing-anchor-ids) anchor text.
-[anchor with explicit ID](#explicit-anchor-ids) | `[id: anchor text]`. Only `anchor text` is rendered.
-[hidden or empty anchors](#hidden-or-empty-anchors) | `[id:]`
-[headers as anchors](#headers-as-anchors) | Same as markdown: `# My header` becomes an anchor referencable as `#my-header`. The space after `#` is required. Unlike markdown, IML allows this to be overridden by inserting an explicit ID at the beginning of the header's content: `# [short-id:]My unwieldy header (and humorous aside)`.
-[definition anchor](#definition-text-anchors) | `[=term with definition in surround paragraph]`. Typically referenced with a [terse hyperlink](#terse-hyperlinks).
+autolinks | Tokens that match URI syntax and that begin with `http://`, `https://`, and `mailto:` are automatically rendered as hyperlinks by intent, unless they are immediately preceded by empty braces, as in `[]http://example.com/dont-make-me-clickable`.
+[simple text anchor](#simple-text-anchors) | `[anchor text]`. ID is [derived from](#comparing-anchor-ids) anchor text. Unlike HTML or markdown, IML allows nested anchors (e.g., where a full sentence is an anchor, a word inside the sentence can also be an anchor).
+[anchor with explicit ID](#explicit-anchor-ids) | `[@id: anchor text]`. Only `anchor text` is rendered.
+[hidden or empty anchors](#hidden-or-empty-anchors) | `[@id:]` (nothing is rendered)
+[headers as anchors](#headers-as-anchors) | Same as markdown: `# My header` becomes an anchor referencable as `#my-header`. The space after `#` is required in the header. Unlike markdown, IML allows the ID for a header to be overridden by inserting an explicit ID at the beginning of the header's content: `# [@short-id:]My unwieldy header (and humorous aside)`.
+[definition anchor](#definition-text-anchors) | `[=term with definition in surrounding paragraph]`. For compatibility with other markdown variants, the close bracket may be preceded by an equals sign: `[=term=]`, though this form is deprecated. Typically referenced with a [terse hyperlink](#terse-hyperlinks).
 [code anchors in IPL](#code-anchors) | Automatic from structure; referenced with dotted notation.
-[anchors for media and other complex content](#anchor-pairs) | `[id ...]content[/]`. Unlike HTML, overlapping anchors are supported.
-[disjoint anchors](#disjoint-anchors) | Add a `+` after at least one instance of a repeated explicit ID: `[id+:anchor text]` and/or `[id+ ...]content[/]`. All content with the same ID becomes part of a single disjoint anchor.
+[anchors for media and other complex content](#anchor-pairs) | `[@id ...]content[/]`. Unlike HTML, overlapping anchors are legal, with some caveats.
+[disjoint anchors](#disjoint-anchors) | Use the same ID more than once. Add a `+` after at least one instance of the repeated explicit ID to clarify that this is intentional: `[@id+:anchor text]` and/or `[@id+ ...]content[/]`. All content with the same ID becomes part of a single disjoint anchor.
 
 ### Anchors
 
@@ -24,7 +33,7 @@ An anchor is a target for a hyperlink -- something we can point *at*. It may be
 
 #### Simple text anchors
 
-The most common thing to point at in intent is text, and the simplest way to make it a pointable target is to enclose it in square brackets. For example, the following paragraph defines anchors around two terms, so they can be referenced elsewhere:
+The most common thing to point at in intent is text, and the simplest way to make it a pointable target is to enclose it in square brackets. For example, the following paragraph defines anchors around "Magnetic resonance imaging" and "MRI", so they can be referenced elsewhere:
 
 ```iml
 [Magnetic resonance imaging] ([MRI]) is a medical imaging
@@ -32,13 +41,13 @@ technique used in radiology to form pictures of the anatomy
 and the physiological processes of the body.
 ```
 
-__Anchor text__ like "Magnetic resonance imaging" in the example above is intended to be visualized inline with the text that surrounds it -- probably un-stylized, and certainly without the square brackets. Enclosing it in square brackets simply delimits the region of the text that can be pointed to:
+__Anchor text__ is intended to be visualized inline with the text that surrounds it -- probably un-stylized, and certainly without the square brackets. Enclosing it in square brackets simply delimits the region of the text that can be pointed to:
 
 ![simple text anchors](../assets/simple-text-anchors.png)
 
 #### Anchor IDs
 
-Each anchor defines one (or more) __anchor IDs__. This is a short, memorable string that uniquely identifies the anchor within its container.
+Each anchor defines one (or more) __anchor IDs__ -- a short, memorable string that uniquely identifies the anchor within its container.
 
 ##### Implicit anchor IDs
 
@@ -46,13 +55,13 @@ The easiest way to define the ID of an anchor is to leave it implicit -- let it
 
 ##### Explicit anchor IDs
 
-It is also possible to customize the ID for an anchor using a more verbose __explicit ID syntax__: `[id: anchor text]`. For example:
+It is also possible to customize the ID for an anchor using a more verbose __explicit ID syntax__: `[+id: anchor text]`. For example, the following IML defines a short ID instead of the one that would have been derived from a longer phrase:
 
 ```i
-The [ww2history: history of World War II] is long and complex.
+The [+ww2history: history of World War II] is long and complex.
 ```
 
-The `id:` prefix can also be added to hyperlinks, making them anchors even as they point elsewhere.
+The `+id:` prefix can also be prepended to the bracketed data inside normal or terse hyperlinks, making the hyperlinks anchors even as they point elsewhere. This can be useful in endnotes.
 
 ##### ID variants
 
@@ -60,7 +69,7 @@ The same anchor can have multiple ID variants; see [Definition Anchors &gt; Infl
 
 ##### Comparing anchor IDs
 
-Whether anchor IDs are implicit or explicit, intent recognizes and compares them in a way that makes them convenient and robust for humans. Minor details are ignored: ID values are trimmed, converted to lower case, and have all runs of punctuation and/or spaces replaced with a single hyphen. This means that the anchor id `MRI` could also be written as `mri`. And this contrived example of an ugly ID:
+Whether anchor IDs are implicit or explicit, intent recognizes and compares them in a way that makes them convenient and robust for humans who might capitalize, space, or punctuate inconsistently. Minor details are ignored: ID values are trimmed, converted to lower case, and have all runs of punctuation and/or spaces replaced with a single hyphen. This means that the anchor id `MRI` could also be written as `mri`. And this contrived example of a really messy ID:
 
     He won't -- or shouldn't, anyway! -- say "Get lost."
 
@@ -68,13 +77,13 @@ Whether anchor IDs are implicit or explicit, intent recognizes and compares them
 
     he-won-t-or-shouldn-t-anyway-say-get-lost
 
-The lower kabob-case form is canonical. However, variants of this ID that are just capitalized or punctuated differently will also be seen as equivalent.
+The lower kabob-case form is canonical and preferred. However, variants of this ID that are just capitalized or punctuated differently will also be seen as equivalent.
 
-In addition, *references* to IDs can be abbreviated with an `*` wildcard, as long as the portion of the ID that remains is unambiguous. In most containers, the long ID above could probably be referenced as `He won't*` or `* say 'Get lost'` or even `he*get-lost`.
+In addition, *references* to IDs can be abbreviated with an `*` wildcard, as long as the portion of the ID that remains is unambiguous. In most containers, the long ID above could probably be referenced as `He won't*` or `* say 'Get lost'` or even `he*get-lost`. This lets IDs be as long as is natural -- but lets references be much terser.
 
 #### Hidden or empty anchors
 
-Sometimes the intent is to anchor a location, rather than anchoring visible content. For example, you might want to point between two words to show someone where a missing piece of content belongs. To do this, simply insert an explicit anchor ID without any anchor text:
+Sometimes the intent is to anchor a *location*, rather than anchoring *visible content*. For example, you might want to point between two words to show someone where a missing piece of content belongs. To do this, simply insert an explicit anchor ID without any anchor text:
 
 ```i
 running text[insert-here:] more running text
@@ -112,12 +121,14 @@ In certain circumstances, an [#MRI] provides diagnostic insight that is unavaila
 
 But what if we wanted to make our term reference plural: "MRIs provide diagnostic insight..."? Now our clickable term ends with `-s`, whereas its definition is the uninflected singular form... There are two solutions: 
 
-* Add __ID variants__ to the anchor: In the definition anchor, do something like this: `[=MRI[id:MRIs]]`; intent renders only the first form in the *in situ* context, but will accept all others as equally valid variants in references. Variants can include the `*` wildcard; `[=invoking|invoc*|invok*]` creates ID variants that match any form of the verb `invoke`.
+* Add __ID variants__ to the anchor: In the definition anchor, do something like this: `[id:MRIs: MRI]`. Intent treats evything will render only the first form in the *in situ* context, but will accept all others as equally valid variants in references. Variants can include the `*` wildcard; `[=invoking|invoc*|invok*]` creates ID variants that match any form of the verb `invoke`.
 
     >Note 1: It also creates some nonsense possibilities like accidentally mapping `[#invoc-o-matic]` to the `invoc*` anchor -- but since the author chooses whether to insert such references, and since definition references can only point at definition anchors, there's little practical difficulty with the fuzzy target.
 
     >Note 2: ID variants are not currently supported for anything except definition anchors. Perhaps they will be supported elsewhere in the future. 
 
+>   >Note 3: This syntax does not allow the pipe character to be part of the  
+
 * Just use a traditional hyperlink in the `[clickable text](#id)` form:
 
     ```iml
@@ -190,61 +201,42 @@ That then I scorn to change my state with [c+:kings].
 
 ### Hyperlinks
 
-A hyperlink is an expression in the form `[@ref|clickable content]`, where `id` is optional and has the same semantics as with anchors (allowing a hyperlink to also be an anchor itself), `anchor` is a target bracketed elsewhere, and `clickable content` is the text or graphic that would be rendered as blue underlined text if the hyperlink were HTML. Additional params--`target` and `base`--can be added between `anchor` and `linked text` using `;` + whitespace, as in:
+A hyperlink is an expression in the form `[+id: clickable content](ref)`, where `+id: ` is optional and has the same semantics as with anchors (allowing a hyperlink to also be an anchor itself), `ref` is an ID defined elsewhere, and `clickable content` is the text or graphic that would be rendered as blue underlined text if the hyperlink were HTML. Additional params--`target` and `base`--can be added between `anchor` and `linked text` using `;` + whitespace, as in:
 
 ```i
-[@https://www.example.com/a/b; target=_blank; rel=author|clickable text]
+[clickable text](https://www.example.com/a/b; target=_blank; rel=author)
 ```
 
-Hyperlinks to simple textual anchors can be shortened so they look like those anchors with an `@` in front of them. To refer to the MRI term from our example above, running text might contain the following hyperlink:
+The expression in the parenthesized portion of the hyperlink can be any relative or absolute URI, including a document fragment like `#fragment`).
 
-```i
-You need to get an [@MRI] as soon as possible.
-```  
-
-Hyperlinks also support a paired variant that follows the same rules as anchors:
+#### Terse Hyperlinks
+Imagine that, somewhere near the end of our imaginary IML document about MRIs, we include the following sentence that refers back to the place where our term was defined:
 
 ```i
-[@https://a.b.com/c; target=_blank ...]clickable content[/] 
+[Magnetic resonance imaging](#magnetic-resonance-imaging) is often expensive.
 ```
 
-...or:
+This works -- but notice how verbose it is. For situations like this, we take advantage of intent's support for fuzzy ID matching, and write a terse form instead:
 
 ```i
-[sample@https://a.b.com/c; target=_blank ...]clickcable content[/sample]
-```
-
-## Interjections
-
-An interjection lets authors manage linked content where it is convenient to create and maintain -- but display it somewhere else. Interjections are intent's way of dealing with things like footnotes, endnotes, callouts, and similar assets. In an editor, interjections are defined inline: inside, next to, or near the content they enhance. However, they may render in an entirely different place such as a footer or an appendix.
-
-An interjection may have one or more __display points__ where its content or some subset or transformation thereof is rendered. 
+[#Magnetic resonance imaging] is often expensive.
+```  
 
-A display point for interjection is defined with an expression in the form `[^@id: anchor content]`, where `id` is a formal identifier for the interjection.
+This combines the referenced ID and the clickable text, making the parenthesized portion of the hyperlink unnecessary. Intent normalizes the bracketed phrase to `magnetic-resonance-imaging` to resolve the hyperlink.
 
-The interjected content (e.g., the text of a footnote, the diagram) is defined at a __definition point__. This may be an anchor in the form `[^id: interjected content]`, or a formally named block that has a type, marks, and other properties. In the latter case, the block should carry the `+interject` mark to indicate that it is not to be displayed as part of the running context.
+Terse hyperlink are both easier to write and easier to read. Their use is encouraged, where they make sense.
 
-Suppose you are using intent to write about some product requirements, and you want to add a footnote about . You might do it like this:
+#### Paired Hyperlinks
+Hyperlinks also support a paired variant that follows the same rules as anchors:
 
 ```i
-We need to make sure that we consider accessibility. Some of our
-customers [^@1: say] that they won't buy unless the product is
-usable by the visually impaired.
-
-[^1: See the focus group done in Sep 2019.]
+[](@https://a.b.com/c; target=_blank ...)clickable content[/] 
 ```
 
-You could also do it like this:
+...or:
 
 ```i
-We need to make sure that we consider accessibility. Some of our
-customers [^@1: say] that they won't buy unless the product is
-usable by the visually impaired.
-
-^1: footnote
-    See the focus group done in Sep 2019.
+[+id:x](https://a.b.com/c; target=_blank ...)clickcable content[/x]
 ```
 
 
-
-
diff --git a/docs/spec/metadata.md b/docs/spec/metadata.md
new file mode 100644
index 00000000..cc7a37f8
--- /dev/null
+++ b/docs/spec/metadata.md
@@ -0,0 +1,24 @@
+Things that intent could expand
+
+* glossary: take all definitions from doc or larger scope and generate a glossary
+* doc stats:
+  * sha1 (git $Id$; see https://git-scm.com/book/en/v2/Customizing-Git-Git-Attributes)
+  * build date
+  * byte count
+  * word count
+  * reading level
+  * author (git)
+  * commit hash
+  * revision number
+  * lastmod date
+* arbitrary expansions (the value of an expression defined elsewhere with an anchor)
+* line num
+* DOM xpath
+* generated id
+* cyclomatic complexity
+* attribs of functions
+  * C-decl func sig / ABI / mangled version
+* attribs of class
+  * packing
+  * inheritance / traits
+* documentation
\ No newline at end of file
diff --git a/docs/spec/tables.md b/docs/spec/tables.md
new file mode 100644
index 00000000..5010d775
--- /dev/null
+++ b/docs/spec/tables.md
@@ -0,0 +1,34 @@
+# Tables
+Intent supports the [table syntax of Github-flavored markdown](https://github.github.com/gfm/#tables-extension-).
+
+Intent also adds some extra features.
+
+## colspan
+A cell (including in the header row) can be given an HTML `colspan` value (merging it with the cell(s) to its right) by preceding its delimiting pipe character with one or more greater-than (`>`) characters (where the number of `>` characters tells how many rightward cells to merge):
+
+```iml
+Month |	Savings
+--- | ---
+January	| $100
+February | $80
+|> Sum : $180
+```
+
+To begin a cell's content with a `>` character, simply put a space between the pipe delimiter and the content.
+
+## rowspan
+A cell can be given an HTML `rowspan` value (merging it with the cell(s) below it) by preceding its delimiting pipe character with one or more underscore (`_`) characters (where the number of `_` characters tells how many downward cells to merge):
+
+
+```iml
+Month | Savings | Savings for holiday!
+--- | --- | ---
+January | $100 |_ $50
+February | $80
+```
+
+To begin a cell's content with a `>` character, simply put a space between the pipe delimiter and the content.
+
+## multiline cells
+
+Table rows in markdown must fit onto a single line. This means that if you want complex substructure inside a cell (e.g., multiple paragraphs, lists), [you must use HTML constructs](https://stackoverflow.com/a/48754707).   
\ No newline at end of file
diff --git a/docs/tests/autolinks.html b/docs/tests/autolinks.html
new file mode 100644
index 00000000..a06f7790
--- /dev/null
+++ b/docs/tests/autolinks.html
@@ -0,0 +1,3 @@
+<p>The following items should each be automatically rendered as hyperlinks: <a href="https://example.com/a">https://example.com/a</a>, <a href="https://example.com/a?x=y">https://example.com/a?x=y</a>, <a href="https://example.com/a#fragment">https://example.com/a#fragment</a>, <a href="https://example.com/a?x=y;a=b#fragment">https://example.com/a?x=y;a=b#fragment</a>, <a href="mailto:fred@flintstones.xyz">mailto:fred@flintstones.xyz</a>.</p>
+
+<p>The following items should NOT be rendered as hyperlinks: ftp://example.com/xyz, urn:example:animal:ferret:nose, www.example.com</p>
\ No newline at end of file
diff --git a/docs/tests/autolinks.i b/docs/tests/autolinks.i
new file mode 100644
index 00000000..ccbe41ed
--- /dev/null
+++ b/docs/tests/autolinks.i
@@ -0,0 +1,3 @@
+The following items should each be automatically rendered as hyperlinks: https://example.com/a, https://example.com/a?x=y, https://example.com/a#fragment, https://example.com/a?x=y;a=b#fragment, mailto:fred@flintstones.xyz.
+
+The following items should NOT be rendered as hyperlinks: ftp://example.com/xyz, urn:example:animal:ferret:nose, www.example.com
\ No newline at end of file
diff --git a/docs/tests/contrived messy ID.html b/docs/tests/contrived messy ID.html
new file mode 100644
index 00000000..7a71dab5
--- /dev/null
+++ b/docs/tests/contrived messy ID.html	
@@ -0,0 +1 @@
+<p>Here is some text with a contrived, messy ID: <a id="he-won-t-or-shouldn-t-anyway-say-get-lost">He won't -- or shouldn't, anyway! -- say "Get lost."</a></p>
\ No newline at end of file
diff --git a/docs/tests/contrived messy ID.i b/docs/tests/contrived messy ID.i
new file mode 100644
index 00000000..169c1da2
--- /dev/null
+++ b/docs/tests/contrived messy ID.i	
@@ -0,0 +1 @@
+Here is some text with a contrived, messy ID: [He won't -- or shouldn't, anyway! -- say "Get lost."]
\ No newline at end of file
diff --git a/docs/tests/normal hyperlink.html b/docs/tests/normal hyperlink.html
new file mode 100644
index 00000000..16277572
--- /dev/null
+++ b/docs/tests/normal hyperlink.html	
@@ -0,0 +1 @@
+<p>This is a <a href="https://example.com/normal">normal hyperlink</a>.</p>
\ No newline at end of file
diff --git a/docs/tests/normal hyperlink.i b/docs/tests/normal hyperlink.i
new file mode 100644
index 00000000..871daec7
--- /dev/null
+++ b/docs/tests/normal hyperlink.i	
@@ -0,0 +1 @@
+This is a [normal hyperlink](https://example.com/normal).
\ No newline at end of file
diff --git a/docs/tests/terse hyperlink.html b/docs/tests/terse hyperlink.html
new file mode 100644
index 00000000..e8dfd792
--- /dev/null
+++ b/docs/tests/terse hyperlink.html	
@@ -0,0 +1 @@
+<p>This is a <a href="#terse-hyperlink">terse hyperlink</a>.</p>
\ No newline at end of file
diff --git a/docs/tests/terse hyperlink.i b/docs/tests/terse hyperlink.i
new file mode 100644
index 00000000..e4e3fbc9
--- /dev/null
+++ b/docs/tests/terse hyperlink.i	
@@ -0,0 +1 @@
+This is a [#terse hyperlink].
\ No newline at end of file