Support parsed metadata

[Shushe] / README.markdown

diff --git a/README.markdown b/README.markdown
index d4399e35a858c3b514e335e22a209150c60904b8..0b4c4b4ef135c7375368a9f78e859964998e4cf2 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`                |
+|     `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`        |
@@ -307,6 +308,12 @@ The following additional variables can be used to control the behaviour
     default, to enable additional rules without overriding the existing
     ones.
 
+- **`DATAOPTS`:**
+  Additional options to use when calling Make during the first stage of a two‐stage build using `DATADIR`.
+
+  This can be used to override variables which are only applicable during the second stage.
+  Note that when supplying this variable on the shell, it will need to be double‐quoted.
+
 - **`DATAEXT`:**
   A list of file extensions which signify “data” files during a two‐stage build using `DATADIR`.
 
@@ -541,6 +548,18 @@ These include :⁠—
 - 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`
@@ -684,6 +703,25 @@ The following params are made available globally in parsers and
 - **`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