Move expansion into its own transform

[Shushe] / README.markdown

diff --git a/README.markdown b/README.markdown
index 70a9730182b25a89b8542b8a8bed91a3aa875931..9b649d21df4eb381c71d27595bbe42c5646e6939 100644 (file)
--- a/README.markdown
+++ b/README.markdown
@@ -188,6 +188,7 @@ This document uses a few name·space prefixes, with the following
 |    `exsl:` | `http://exslt.org/common`                     |
 | `exslstr:` | `http://exslt.org/strings`                    |
 |    `html:` | `http://www.w3.org/1999/xhtml`                |
 |    `exsl:` | `http://exslt.org/common`                     |
 | `exslstr:` | `http://exslt.org/strings`                    |
 |    `html:` | `http://www.w3.org/1999/xhtml`                |

+|     `rdf:` | `http://www.w3.org/1999/02/22-rdf-syntax-ns#` |

 |     `svg:` | `http://www.w3.org/2000/svg`                  |
 |   `xlink:` | `http://www.w3.org/1999/xlink`                |
 |    `xslt:` | `http://www.w3.org/1999/XSL/Transform`        |
 |     `svg:` | `http://www.w3.org/2000/svg`                  |
 |   `xlink:` | `http://www.w3.org/1999/xlink`                |
 |    `xslt:` | `http://www.w3.org/1999/XSL/Transform`        |


@@ -547,6 +548,18 @@ These include :⁠—
 - A `@书社:media-type` attribute, giving the identified media type of
     the plaintext node.
 
 - A `@书社:media-type` attribute, giving the identified media type of
     the plaintext node.
 

+### Parsed metadata
+
+It is possible to extract metadata from a document at the same time as
+  it is being parsed.
+This is done by creating result elements in the `书社:about` mode;
+  these should be R·D·F property elements which apply to the conceptual
+  entity that is the document being parsed.
+
+During transformation, metadata for the file with identifier `$FILE`
+  can be read from the children of
+  `$书社:about//*[@rdf:about=$FILE]/nie:interpretedAs/*`.
+

 ## Output Redirection
 
 By default, ⛩📰 书社 installs files to the same location in `DESTDIR`
 ## Output Redirection
 
 By default, ⛩📰 书社 installs files to the same location in `DESTDIR`


@@ -620,6 +633,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


@@ -690,6 +706,25 @@ The following params are made available globally in parsers and
 - **`THISREV`:**
   The value of the `THISREV` variable (if present).
 
 - **`THISREV`:**
   The value of the `THISREV` variable (if present).
 

+In transforms, the following params are additionally available :⁠—
+
+- **`书社:about`:**
+  R·D·F metadata about all of the documents ⛩📰 书社 knows about.
+  Use `$书社:about//*[@rdf:about=$IDENTIFIER]` to get the metadata for
+    the current document.
+
+- **`书社:source`:**
+  The parsed source document being transformed, prior to any expansion.
+
+- **`书社:expansion`:**
+  The document after the all embeds have been expanded.
+  Unavailable during the `书社:expand` stage.
+
+- **`书社:result`:**
+  The document after the main set of transformations have been applied.
+  Only available during the `书社:finalize` stage, where it is used to
+    apply output wrapping and other clean·up.
+

 ## Output Wrapping
 
 Provided at least one toplevel result element belongs to the H·T·M·L
 ## Output Wrapping
 
 Provided at least one toplevel result element belongs to the H·T·M·L