Provide metadata in transform; add attributes there

[Shushe] / README.markdown

diff --git a/README.markdown b/README.markdown
index e70361e3160b68b98656993439f61f38f36d5f52..e5a24eddc675297b11551834d15673f74dea3568 100644 (file)
--- a/README.markdown
+++ b/README.markdown
@@ -464,32 +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 :⁠—
 
-- For toplevel result 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 `@书社:cksum` attribute giving the `cksum` checksum of the
-      corresponding source file.
+- A `@书社:media-type` attribute, giving the identified media type of
+    the plaintext node.
 
-  - 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 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.)
+## 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
 
@@ -516,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
 
@@ -609,9 +620,6 @@ The following params are made available globally in parsers and
 
 The following params are only available in transforms :⁠—
 
-- **`METADATA`:**
-  The path of the metadata file (within `BUILDDIR`).
-
 - **`PATH`:**
   The path of the output file (within `DESTDIR`).