Provide metadata in transform; add attributes there

[Shushe] / README.markdown

diff --git a/README.markdown b/README.markdown
index 2cefb62ae9079e0fc99979fb61d531a2a6666d6c..e5a24eddc675297b11551834d15673f74dea3568 100644 (file)
--- a/README.markdown
+++ b/README.markdown
@@ -283,6 +283,8 @@ The following additional variables can be used to control the behaviour
     those which end with a cloparen, and those which contain a hash,
     buck, percent, asterisk, colon, semi, eroteme, bracket, backslash,
     or pipe.
+  It is important that these rules not produce any output, as anything
+    printed to `stdout` will be considered a result of the find.
 
 - **`EXTRAFINDRULES`:**
   The value of this variable is appended to `FINDRULES` by default, to
@@ -317,6 +319,11 @@ The following additional variables can be used to control the behaviour
   A white·space‐separated list of media types or media type suffixes to
     consider X·M·L (default: `application/xml text/xml +xml`).
 
+- **`FINALIZE`:**
+  A program to run on (unspecial) X·M·L files after they are
+    transformed (default: `xmllint --nonet --nsclean`).
+  This variable can be used for postprocessing.
+
 - **`THISREV`:**
   The current version of ⛩️📰 书社 (default: derived from the current
     git tag/branch/commit).
@@ -457,23 +464,27 @@ It is **strongly recommended** that auxillary templates in parsers be
 
 ### Attributes added during parsing
 
-⛩️📰 书社 will add a few attributes to the output of the parsing step,
-  namely :⁠—
+⛩️📰 书社 will add a few attributes to elements which result from
+  parsing plaintext `<html:script>` elements.
+These include :⁠—
 
-- A `@书社:cksum` attribute on toplevel result elements, giving the
-    `cksum` checksum of the corresponding source file.
+- 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.)
 
-- For the elements which result from parsing plaintext `<html:script>`
-    elements :⁠—
+- A `@书社:media-type` attribute, giving the identified media type of
+    the plaintext node.
 
-  - 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.)
+## Output Redirection
 
-  - A `@书社:media-type` attribute, giving the identified media type of
-      the plaintext node.
+By default, ⛩️📰 书社 installs files to the same location in `DESTDIR`
+  as they were placed in their `SRCDIR`.
+This behaviour can be customized by setting the `@书社:destination`
+  attribute on the root element, whose value can give a different path.
+This attribute is read after parsing, but before transformation (where
+  it is silently dropped).
 
 ## Embedding
 
@@ -500,14 +511,30 @@ Embedding takes place after parsing but before transformation, so
   and update them accordingly; it will signal an error if the
   dependencies are recursive.
 
-## Output Redirection
+### Attributes added during expansion
 
-By default, ⛩️📰 书社 installs files to the same location in `DESTDIR`
-  as they were placed in their `SRCDIR`.
-This behaviour can be customized by setting the `@书社:destination`
-  attribute on the root element, whose value can give a different path.
-This attribute is read after parsing, but before transformation (where
-  it is silently dropped).
+⛩️📰 书社 will add a few attributes to toplevel result elements, both
+  in the main document and any embedded documents, during the expansion
+  phase prior to the main transformation.
+These include :⁠—
+
+- A `@书社:cksum` attribute giving the `cksum` checksum of the
+    corresponding source file.
+
+- A `@书社:mtime` attribute giving the last modified time of the
+    corresponding source file.
+
+- A `@书社:identifier` attribute giving the ⛩️📰 书社 identifier
+    (i·e, starting with `about:shushe?`) of the corresponding source
+    file.
+
+- For elements in the `html` namespace, an `itemscope` attribute and an
+    `itemtype` attribute with a value of
+    `urn:fdc:ladys.computer:20231231:Shu1She4:document` (for the main
+    document) or `urn:fdc:ladys.computer:20231231:Shu1She4:embed` (for
+    embedded documents).
+  These attributes are used to scope any nested `<html:meta>` elements
+    with `@itemprop` attributes to their containing documents.
 
 ## Transforms
 
@@ -581,9 +608,6 @@ The following params are made available globally in parsers and
 - **`BUILDTIME`:**
   The current time.
 
-- **`CKSUM`:**
-  The checksum of the source file (⅌ `cksum`).
-
 - **`IDENTIFIER`:**
   The ⛩️📰 书社 identifier of the source file (a u·r·i beginning with
     `about:shushe`).
@@ -591,17 +615,11 @@ The following params are made available globally in parsers and
 - **`SRCREV`:**
   The value of the `SRCREV` variable (if present).
 
-- **`SRCTIME`:**
-  The time at which the source file was last modified.
-
 - **`THISREV`:**
   The value of the `THISREV` variable (if present).
 
 The following params are only available in transforms :⁠—
 
-- **`CATALOG`:**
-  The path of the catalog file (within `BUILDDIR`).
-
 - **`PATH`:**
   The path of the output file (within `DESTDIR`).