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).
 
 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>`
 ## 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`.
 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`.
   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
 
 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.
 
   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,
 ## 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.
 
   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
 - **`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 :⁠—
 
 
 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
 - **`书社:about`:**
   R·D·F metadata about all of the documents ⛩📰 书社 knows about.
   Use `$书社:about//*[@rdf:about=$IDENTIFIER]` to get the metadata for