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`                |
 |    `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`        |


@@ -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.
 
     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`.
 
 - **`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.
 
 - 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`


@@ -684,6 +703,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