Refactor transforms & add 书社:application stage

[Shushe] / README.markdown

diff --git a/README.markdown b/README.markdown
index 885fe751dcd580ec353e52d2c1162f2eab7df1bd..f6a08642353a226246ec11eaa60b873e764cfb1d 100644 (file)
--- a/README.markdown
+++ b/README.markdown
@@ -214,11 +214,8 @@ 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
+- **`THISREV`:**
+  The current version of ⛩️📰 书社 (default: derived from the current
     git tag/branch/commit).
 
 - **`SRCREV`:**
@@ -382,6 +379,8 @@ Embeds are replaced with the parsed contents of a file, unless the file
   is an asset, in which case an `<html:object>` element is produced
   instead (with the contents of the asset file provided as a base64
   `data:` u·r·i).
+Embed replacements will be given a `@书社:identifier` attribute whose
+  value will match the `@xlink:href` of the embed.
 
 Embedding takes place after parsing but before transformation, so
   parsers are able to generate their own embeds.
@@ -404,14 +403,6 @@ Transforms are used to convert X·M·L files into their final output,
   after all necessary parsing and embedding has taken place.
 ⛩️📰 书社 comes with some transforms; namely :⁠—
 
-- **`transforms/attributes.xslt`:**
-  Applies transforms to the children of any `<书社:apply-attributes>`
-    elements, and then applies the attributes of the
-    `<书社:apply-attributes>` to each result child, replacing the
-    element with the result.
-  This is useful in combination with image embeds to apply alt‐text to
-    the resulting `<html:img>`.
-
 - **`transforms/asset.xslt`:**
   Converts `<html:object>` elements which correspond to recognized
     media types into the appropriate H·T·M·L elements, and deletes
@@ -426,8 +417,8 @@ Transforms are used to convert X·M·L files into their final output,
   - **`urn:fdc:ladys.computer:20231231:Shu1She4:title`:**
     Provides the title of the page.
 
-  ⛩️📰 书社 automatically encapsulates embeds so that their metadata
-    does not propogate up to the embedding document.
+  ⛩️📰 书社 automatically encapsulates H·T·M·L embeds so that their
+    metadata does not propogate up to the embedding document.
   To undo this behaviour, remove the `@itemscope` and `@itemtype`
     attributes from the embed during the transformation phase.
 
@@ -454,8 +445,9 @@ The following params are made available globally in parsers and
 - **`CKSUM`:**
   The checksum of the source file (⅌ `cksum`).
 
-- **`GENERATOR`:**
-  The value of the `GENERATOR` variable (if present).
+- **`IDENTIFIER`:**
+  The ⛩️📰 书社 identifier of the source file (a u·r·i beginning with
+    `about:shushe`).
 
 - **`SRCREV`:**
   The value of the `SRCREV` variable (if present).
@@ -463,8 +455,8 @@ The following params are made available globally in parsers and
 - **`SRCTIME`:**
   The time at which the source file was last modified.
 
-- **`VERSION`:**
-  The value of the `VERSION` variable (if present).
+- **`THISREV`:**
+  The value of the `THISREV` variable (if present).
 
 The following params are only available in transforms :⁠—
 
@@ -526,6 +518,29 @@ This mechanism can be used to allow transforms to insert content
 Output wrapping can be entirely disabled by adding a
   `@书社:disable-output-wrapping` attribute to the top‐level element in
   the result tree.
+This attribute will also prevent wrapping non‐H·T·M·L embeds with an
+  `<html:div>`.
+
+## Applying Attributes
+
+The `<书社:apply-attributes>` element will apply any attributes on the
+  element to the element(s) it wraps.
+It is especially useful in combination with embeds.
+
+The `<书社:apply-attributes-to-root>` element will apply any attributes
+  on the element to the root node of the final transformation result.
+It is especially useful in combination with output wrapping.
+
+In both cases, attributes from various sources are combined with
+  white·space between them.
+Attribute application takes place after all ordinary transforms have
+  completed.
+
+Both elements ignore attributes in the `xml:` namespace, except for
+  `@xml:lang`, which ignores all but the first definition (including
+  any already present on the root element).
+On H·T·M·L and S·V·G elements, `@lang` has the same behaviour as
+  `@xml:lang`.
 
 ## License