Update the docs.

README.md

@@ -162,6 +162,10 @@ const xml = minifyXML(
 )
 ```
 
+### Markup 
+
+See [the Markup documentation](./docs/markup.md).
+
 ### Components
 
 See [the Components documentation](./docs/components.md).

docs/components.md

@@ -1,5 +1,19 @@
 # Components
 
+## Architecture
+
+Fundamentally, we want to do (approximately) 4 steps, some of which are
+optional.
+
+1. Template parsing.      Transforms templates into ASTs.
+1. Template integration.  Combines two templates into a single template.
+1. Content parsing.       Structures content for template AST rendering.
+1. Rendering.             Concretize the AST into a document structure with
+                          the available content added.
+
+
+## Thoughts
+
 It is not at all clear to me that components should be in HTML.  It seems
 like a natural starting point, though, since we want to stay close to our
 bare-metal technologies.
@@ -7,6 +21,16 @@ bare-metal technologies.
 Perhaps components should be in the style of HTML or JSX fragments.  I
 borrowed heavily from Svelte for this.
 
+I'm somewhat dissatisfied with the syntax of svelte's "directives" like
+{#if} and {/if}.  They feel like they were put in as a concession to
+script interpolation.  I think I prefer the JSX approach that uses {}
+to run arbitrary script content.  
+
+I don't know if there's any concepts we should bring in from XSLT for
+this, but it's already a technology mechanis,
+
+
+
 ```
 // This "<loom-module>" tag could be created automatically before inserting.
 <loom-module>
@@ -16,16 +40,16 @@ borrowed heavily from Svelte for this.
      *  - Assume ES6?
      *  - Maybe allow other languages that transpile to JS?
      *  - Automatically sandbox css?
+     *  - Everything here needs to be available only during interpretation
+     *    of this HTML and css.
      */
-
   </script>
 
   <ul>
     <li>Allow multiple comment styles?</li>
     <li>Plugin-based transformations (AST)</li>
     <li>Some kind of script scoping</li>
-    <li></li>
-    <li></li>
+    <li>Allow some bits of code using JSX-style {} syntax.</li>
   </ul>
 
   <style type="test/scss">

docs/markup.md

@@ -0,0 +1,107 @@
+# Markup 
+
+## Considerations
+
+Hypothetically, markup doesn't really matter for this.  A component is a
+component if it can be translated into an AST that a renderer can render.
+
+Practically, markup matters a lot.  People will have strong preferences
+about their favourite versions of things.  One solution to this is to open
+everything wide:  "Just make parsers, transformers, and renderers that suit
+your need."  The advantage of this is it gives people a lot of power to do
+whatever they want.  Practically, the disadvantage is that poor taste will
+prevail.  This is mostly just because good taste requires lots of hard work
+and most people haven't had time to do sufficient hard work to have good
+taste (disregarding the tendency not to want to do that work).  It's
+probably worth noting that good taste can have strong aesthetic differences.
+Two people who disagree strongly can both have excellent tastes, differing
+in influences.
+
+I think the approach I prefer is to leave it open in principle but obscured
+from most consumers of the tool.  This would be effectively to make the Loom
+toolkit work with any style of markup and plugins, but not to popularize
+that feature (for quite some time), preferring instead to create
+concretizations of the toolkit in the form of frameworks.  These will help
+guide consumers in taste, while not restricting those who want to apply more
+work to develop their own aesthetic sensibilities.
+
+## Key Elements
+
+Fundamentally, we want to integrate _form data_ with _content data_.  There
+are probably better and worse paradigms for how to accomplish this.  I'd say
+probably _logic_ style.  This is a paradigm that would let
+producers ignore the mechanisms of integration.
+
+Another excellent (and opposite) approach could be a _functional_ style.  In
+this paradigm, the producer is concerned with mechanisms of data
+transformation.
+
+## Other thoughts
+
+It is not at all clear to me that components should be in HTML.  It seems
+like a natural starting point, though, since we want to stay close to our
+bare-metal technologies.
+
+Perhaps components should be in the style of HTML or JSX fragments.  I
+borrowed heavily from Svelte for this.
+
+I'm somewhat dissatisfied with the syntax of svelte's "directives" like
+{#if} and {/if}.  They feel like they were put in as a concession to
+script interpolation.  I think I prefer the JSX approach that uses {}
+to run arbitrary script content.  
+
+I don't know if there's any concepts we should bring in from XSLT for
+this, but it's already a technology mechanism that operates in this domain.
+
+
+
+```
+// This "<loom-module>" tag could be created automatically before inserting.
+<loom-module>
+  <script type="text/loom-module">
+    /**
+     * Key script features:
+     *  - Assume ES6?
+     *  - Maybe allow other languages that transpile to JS?
+     *  - Automatically sandbox css?
+     *  - Everything here needs to be available only during interpretation
+     *    of this HTML and css.
+     */
+  </script>
+
+  <ul>
+    <li>Allow multiple comment styles?</li>
+    <li>Plugin-based transformations (AST)</li>
+    <li>Some kind of script scoping</li>
+    <li>Allow some bits of code using JSX-style {} syntax.</li>
+  </ul>
+
+  <style type="test/scss">
+    /**
+     * Key styling features:
+     * 
+     *  - Allow all three comment types here?  Make this a setting?
+     *  - Bake-in postcss transformers?  Maybe project-agnostic...
+     *  - Automatically sandbox css
+     */
+  </style>
+
+</loom-module>
+```
+
+
+If the component defines something like this:
+
+```
+<script>
+import Item from 'https://.../Item.component.xml';
+</script>
+
+<Item data={item}/>
+```
+
+Then the "import" node of the AST would be replaced by a function that
+provides the requested content (from Item.component.xml) like a macro.  When
+the `<Item/>` node is hit, it will be interpreted according to the imported
+component macro.
+