Update parser documentation

[Shushe] / README.markdown

diff --git a/README.markdown b/README.markdown
index 573fb86e51fe59b89c2ac7586986d5a23330c71b..885fe751dcd580ec353e52d2c1162f2eab7df1bd 100644 (file)
--- a/README.markdown
+++ b/README.markdown
@@ -102,6 +102,7 @@ In every case, you may supply your own implementation by overriding the
 
 - `awk`
 - `cat`
+- `cksum`
 - `cp`
 - `date`
 - `echo`
@@ -271,16 +272,15 @@ Parsers are used to convert plaintext files into X·M·L trees, as well
 ⛩️📰 书社 comes with some parsers; namely :⁠—
 
 - **`parsers/plain.xslt`:**
-  Wraps `text/plain` contents in a `<html:pre class="plain">` element.
+  Wraps `text/plain` contents in a `<html:pre>` element.
 
 - **`parsers/record-jar.xslt`:**
-  Converts `text/record-jar` contents into a
-    `<html:div class="record-jar">` of `<html:dl>` elements (one for
-    each record).
+  Converts `text/record-jar` contents into a `<html:div>` of
+    `<html:dl>` elements (one for each record).
 
 - **`parsers/tsv.xslt`:**
-  Converts `text/tab-separated-values` contents into an
-    `<html:table class="tsv">` element.
+  Converts `text/tab-separated-values` contents into an `<html:table>`
+    element.
 
 New ⛩️📰 书社 parsers which target plaintext formats should have an
   `<xslt:template>` element with no `@name` or `@mode` and whose
@@ -346,6 +346,26 @@ It is **strongly recommended** that auxillary templates in parsers be
   namespaced (by `@name` or `@mode`) whenever possible, to avoid
   conflicts between parsers.
 
+### Attributes added during parsing
+
+⛩️📰 书社 will add a few attributes to the output of the parsing step,
+  namely :⁠—
+
+- A `@书社:cksum` attribute on toplevel result elements, giving the
+    `cksum` checksum of the corresponding source file.
+
+- For the elements which result from parsing plaintext `<html:script>`
+    elements :⁠—
+
+  - A `@书社:parsed-by` attribute, giving a space‐separated list of
+      parsers which parsed the node.
+    (Generally, this will be a list of one, but it is possible for the
+      result of a parse to be another plaintext node, which may be
+      parsed by a different parser.)
+
+  - A `@书社:media-type` attribute, giving the identified media type of
+      the plaintext node.
+
 ## Embedding
 
 Documents can be embedded in other documents using a `<书社:link>`
@@ -431,6 +451,9 @@ The following params are made available globally in parsers and
 - **`BUILDTIME`:**
   The current time.
 
+- **`CKSUM`:**
+  The checksum of the source file (⅌ `cksum`).
+
 - **`GENERATOR`:**
   The value of the `GENERATOR` variable (if present).