Provide source file in metadata to transforms

[Shushe] / README.markdown

diff --git a/README.markdown b/README.markdown
index bed7a115a4f5fa6a1db7ab165669523d07e872f8..31a73336f7291c926acbd8345e513504267de084 100644 (file)
--- a/README.markdown
+++ b/README.markdown
@@ -547,6 +547,8 @@ Transforms are used to convert X·M·L files into their final output,
     media types into the appropriate H·T·M·L elements, and deletes
     `<html:style>` elements from the body of the document and moves
     them to the head.
+  This conversion happens during the application phase, after the main
+    transformation.
 
 - **`transforms/metadata.xslt`:**
   Provides basic `<html:head>` metadata.
@@ -618,18 +620,19 @@ The following params are made available globally in parsers and
 - **`THISREV`:**
   The value of the `THISREV` variable (if present).
 
-The following params are only available in transforms :⁠—
-
-- **`PATH`:**
-  The path of the output file (within `DESTDIR`).
-
 ## Output Wrapping
 
-⛩📰 书社 will wrap the final output of the transforms in appropriate
-  `<html:html>` and `<html:body>` elements, so it is not necessary for
-  transforms to do this explicitly.
-After performing the initial transform, ⛩📰 书社 will match the root
-  node of the result in the following modes to fill in areas of the
+Provided at least one toplevel result element belongs to the H·T·M·L
+  namespace, ⛩📰 书社 will wrap the final output of the transforms in
+  appropriate `<html:html>` and `<html:body>` elements, so it is not
+  necessary for transforms to do this explicitly.
+If a toplevel result element _is_ a `<html:html>` and `<html:body>`
+  element, it will be merged with the one that ⛩📰 书社 creates.
+Consequently, wrapping the result in a `<html:body>` element can be
+  used to enable wrapping for non‐H·T·M·L content, when desired.
+
+As a part of this process, after performing the initial transform
+  ⛩📰 书社 will match in the following modes to fill in areas of the
   wrapper :⁠—
 
 - **`书社:header`:**
@@ -644,16 +647,13 @@ After performing the initial transform, ⛩📰 书社 will match the root
   The result of matching in this mode is inserted into the
     `<html:head>` of the output.
 
-In addition to being called with the transform result, each of these
-  modes will additionally be called with a `<xslt:include>` element
-  corresponding to each transform.
-If a transform has a `<书社:id>` top‐level element whose value is an
-  i·r·i, its `<xslt:include>` element will have a corresponding
-  `@书社:id` attribute.
-This mechanism can be used to allow transforms to insert content
-  without matching any elements in the result; for example, the
-  following transform adds a link to a stylesheet to the `<html:head>`
-  of every page :⁠—
+The document being matched will contain the full transform result
+  prior to wrapping as well as an `<书社:id>` element for each
+  transform.
+The latter elements can be matched to enable transforms to provide
+  content _without_ matching any elements in the result; for example,
+  the following transform adds a link to a stylesheet to the
+  `<html:head>` of every page :⁠—
 
 ```xml
 <?xml version="1.0"?>
@@ -666,7 +666,7 @@ This mechanism can be used to allow transforms to insert content
   version="1.0"
 >
   <书社:id>example:add-stylesheet-links.xslt</书社:id>
-  <template match="xslt:include[@书社:id='example:add-stylesheet-links.xslt']" mode="书社:metadata">
+  <template match="书社:id[string(.)='example:add-stylesheet-links.xslt']" mode="书社:metadata">
     <html:link rel="stylesheet" type="text/css" href="/style.css"/>
   </template>
 </transform>
@@ -677,7 +677,8 @@ Output wrapping can be entirely disabled by adding a
   the result tree.
 It will not be performed on outputs whose root elements are
   `<书社:archive>`, `<书社:base64-binary>`, or `<书社:raw-text>`
-  (described below).
+  (described below), or on result trees which do not contain a toplevel
+  element in the H·T·M·L namespace.
 
 ## Applying Attributes