Support “soft” dependencies

[Shushe] / README.markdown

diff --git a/README.markdown b/README.markdown
index 0b4c4b4ef135c7375368a9f78e859964998e4cf2..be400b9e2b9a4c9d9e24830dc5d53977e6fe7b0e 100644 (file)
--- a/README.markdown
+++ b/README.markdown
@@ -569,10 +569,14 @@ This behaviour can be customized by setting the `@书社:destination`
 This attribute is read after parsing, but before transformation (where
   it is silently dropped).
 
+Multiple destinations can be provided if the same file should be output to multiple places.
+The file is retransformed each time, with the value of the `DESTINATION` global param set appropriately.
+
 ## Embedding
 
 Documents can be embedded in other documents using a `<书社:link>`
-  element with `@xlink:show="embed"`.
+  element with `@xlink:show="embed"` and an `@xlink:actuate` which is
+  absent or `"none"`.
 The `@xlink:href`s of these elements should have the format
   `about:shushe?source=<path>`, where `<path>` provides the path to the
   file within `SRCDIR`.
@@ -580,6 +584,8 @@ Includes, which do not generate outputs of their own but may still be
   freely embedded, instead use the format
   `about:shushe?include=<path>`, where `<path>` provides the path
   within `INCLUDEDIR`.
+If `<path>` indicates a directory and ends with a slash (`/`),
+  everything within that directory will be embedded.
 
 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
@@ -619,6 +625,40 @@ These include :⁠—
   These attributes are used to scope any nested `<html:meta>` elements
     with `@itemprop` attributes to their containing documents.
 
+## Soft Dependencies
+
+When a file depends only on the metadata of another file, and not its
+  contents, it can be added as a soft dependency rather than an embed.
+Soft dependencies are indicated using a `<书社:link>` element with an
+  `@xlink:show` of `"other"`, `"none"`, or absent, and an
+  `@xlink:actuate` which is absent or `"none"`.
+A change to a soft dependency requires a file to be rebuilt, but no
+  embedding occurs automatically.
+Because there is no automatic embedding, soft dependencies are allowed
+  to be recursive.
+
+The `@xlink:href`s of soft dependency `<书社:link>`s are processed in
+  exactly the same fashion as embeds, described above.
+
+If the value of `@xlink:show` is `"other"`, the soft dependency is
+  transitive.
+Any dependencies of the indicated file which have a `@name` which
+  matches that of the referencing `<书社:link>` element will also be
+  treated as soft dependencies.
+If no `@name` is given, it is treated as the empty string.
+
+When a document is embedded directly, all of its soft dependencies are
+  also treated as soft dependencies of the embedding object.
+However, a document is embedded in a transitive soft dependency, the
+  embed is treated exactly as tho it were itself a transitive soft
+  dependency.
+That means it must have a matching `@name` to be included, and
+  like·wise for any embeds or soft dependencies it contains.
+
+If the value of `@xlink:show` is `"none"` or absent, the soft
+  dependency is not transitive and its own dependencies are not
+  checked.
+
 ## Transforms
 
 Transforms are used to convert X·M·L files into their final output,
@@ -633,6 +673,9 @@ Transforms are used to convert X·M·L files into their final output,
   This conversion happens during the finalization phase, after the main
     transformation.
 
+- **`transforms/expansion.xslt`:**
+  Performs embedding, as described above.
+
 - **`transforms/metadata.xslt`:**
   Provides basic `<html:head>` metadata.
   This metadata is generated from `<html:meta>` elements with one of
@@ -705,6 +748,9 @@ The following params are made available globally in parsers and
 
 In transforms, the following params are additionally available :⁠—
 
+- **`DESTINATION`:**
+  The destination being targeted by this transform.
+
 - **`书社:about`:**
   R·D·F metadata about all of the documents ⛩📰 书社 knows about.
   Use `$书社:about//*[@rdf:about=$IDENTIFIER]` to get the metadata for