various bits of progress

Signed-off-by: dhh1128 <[email protected]>

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.
 

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.
+```
+
+
+

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.

docs/spec/hypertext-state.md

@@ -0,0 +1,14 @@
+State machine for parsing hypertext
+
+  | [ | [+ | [= | [# | : | \] | @ | 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
+