Replace GENERATOR and VERSION with THISREV

[Shushe] / README.markdown

diff --git a/README.markdown b/README.markdown
index 654904ae9eda3ab787fbdc83dc7b001778f5ffda..6b4f06ed18627a3a8dc344f94b5595b74bb85ba3 100644 (file)
--- a/README.markdown
+++ b/README.markdown
@@ -102,12 +102,14 @@ In every case, you may supply your own implementation by overriding the
 
 - `awk`
 - `cat`
+- `cksum`
 - `cp`
 - `date`
 - `echo`
 - `file`
 - `find`
 - `git` (optional; set `GIT=` to disable)
+- `ln`
 - `mkdir` (requires support for `-p`)
 - `mv`
 - `od` (requires support for `-t x1`)
@@ -164,14 +166,20 @@ The following additional variables can be used to control the behaviour
   This variable is used to find the ⛩️📰 书社 `lib/` folder, which is
     expected to be in the same location.
 
-- **`MAGICDIR`:**
-  The location of the magic files to use (default: `$(THISDIR)/magic`).
+- **`MAGIC`:**
+  A white·space‐separated list of magic files to use (default:
+    `$(THISDIR)/magic/*`).
+
+- **`EXTRAMAGIC`:**
+  The value of this variable is appended to `MAGIC` by default, to
+    enable additional magic files without overriding the existing ones.
 
 - **`FINDRULES`:**
   Rules to use with `find` when searching for source files.
-  The default ignores files that start with a period or hyphen‐minus
-    and those which contain a hash, buck, percent, asterisk, colon,
-    semi, eroteme, bracket, backslash, or pipe.
+  The default ignores files that start with a period or hyphen‐minus,
+    those which end with a cloparen, and those which contain a hash,
+    buck, percent, asterisk, colon, semi, eroteme, bracket, backslash,
+    or pipe.
 
 - **`EXTRAFINDRULES`:**
   The value of this variable is appended to `FINDRULES` by default, to
@@ -206,6 +214,14 @@ 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`).
 
+- **`THISREV`:**
+  The current version of ⛩️📰 书社 (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).
@@ -238,9 +254,12 @@ Source files whose media type does not have an associated X·S·L·T
   contain Ascii white·space, colons (`:`), semis (`;`), pipes (`|`),
   bucks (`$`), percents (`%`), hashes (`#`), asterisks (`*`), brackets
   (`[` or `]`), erotemes (`?`), backslashes (`\`), or control
-  characters, and must not begin with a hyphen‐minus (`-`).**
+  characters, must not begin with a hyphen‐minus (`-`), and must not
+  end with a cloparen (`)`).**
 The former characters have the potential to conflict with make syntax,
-  and a leading hyphen‐minus is confusable for a command‐line argument.
+  a leading hyphen‐minus is confusable for a command‐line argument, and
+  a trailing cloparen [activates a bug in G·N·U Make
+  3.81](https://stackoverflow.com/questions/17148468/capturing-filenames-including-parentheses-with-gnu-makes-wildcard-function#comment24825307_17148894).
 
 ## Parsers
 
@@ -250,16 +269,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
@@ -325,6 +343,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>`
@@ -410,16 +448,17 @@ The following params are made available globally in parsers and
 - **`BUILDTIME`:**
   The current time.
 
+- **`CKSUM`:**
+  The checksum of the source file (⅌ `cksum`).
+
 - **`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).
+- **`THISREV`:**
+  The value of the `THISREV` variable (if present).
 
 The following params are only available in transforms :⁠—