Refactor transforms & add 书社:application stage

[Shushe] / README.markdown

diff --git a/README.markdown b/README.markdown
index 6b4f06ed18627a3a8dc344f94b5595b74bb85ba3..f6a08642353a226246ec11eaa60b873e764cfb1d 100644 (file)
--- a/README.markdown
+++ b/README.markdown
@@ -379,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.
@@ -401,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
@@ -423,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.
 
@@ -451,6 +445,10 @@ The following params are made available globally in parsers and
 - **`CKSUM`:**
   The checksum of the source file (⅌ `cksum`).
 
+- **`IDENTIFIER`:**
+  The ⛩️📰 书社 identifier of the source file (a u·r·i beginning with
+    `about:shushe`).
+
 - **`SRCREV`:**
   The value of the `SRCREV` variable (if present).
 
@@ -520,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