Update parser documentation

[Shushe] / README.markdown

diff --git a/README.markdown b/README.markdown
index e2838fad0204817504137d83002e34ca4f0b528e..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`
@@ -213,6 +214,17 @@ The following additional variables can be used to control the behaviour
   A white·space‐separated list of media types to consider X·M·L
     (default: `application/xml text/xml`).
 
+- **`GENERATOR`:**
+  The name of the generator program (default: `⛩️📰 书社`).
+
+- **`VERSION`:**
+  The current version of `GENERATOR` (default: derived from the current
+    git tag/branch/commit).
+
+- **`SRCREV`:**
+  The current version of the source files (default: derived from the
+    current git tag/branch/commit).
+
 - **`VERBOSE`:**
   If this variable has a value, every recipe instruction will be
     printed when it runs (default: empty).
@@ -260,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
@@ -335,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>`
@@ -420,16 +451,20 @@ 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).
+
 - **`SRCREV`:**
-  The tag or hash of the current commit in the working directory (if
-    `GIT` is defined and `./.git` exists).
+  The value of the `SRCREV` variable (if present).
 
 - **`SRCTIME`:**
   The time at which the source file was last modified.
 
 - **`VERSION`:**
-  The tag or hash of the current commit in `THISDIR` (if `GIT` is
-    defined and `$(THISDIR)/.git` exists).
+  The value of the `VERSION` variable (if present).
 
 The following params are only available in transforms :⁠—