Don’t use literal result elements in parsers

[Shushe] / README.markdown

diff --git a/README.markdown b/README.markdown
index 37cc7f7cd7ff8b5f00284bde7c735ce46629bdb6..af78725ca5fbbe8ff42789a6e0ae25b620979606 100644 (file)
--- a/README.markdown
+++ b/README.markdown
@@ -244,6 +244,14 @@ The following additional variables can be used to control the behaviour
   Multiple include directories can be provided, so long as the same
     file subpath doesn’t exist in more than one of them.
 
+- **`DATADIR`:**
+  If set to the location of a directory, ⛩📰 书社 will run a two‐stage build.
+  In the first stage, only files in `SRCDIR` which match `FINDDATARULES` (see below) will be built, with files in `DATADIR` serving as includes.
+  In the second stage, the remaining files in `SRCDIR` will be built, with the files built during the first stage, in addition to any files in `INCLUDEDIR`, serving as includes.
+  Files built during the first stage are copied into `DESTDIR` alongside those from the second stage when installing.
+
+  This functionality is intended for sites where the bulk of the site can be built from a few data files which are expensive to create.
+
 - **`BUILDDIR`:**
   The location of the (temporary) build directory (default: `build`).
   `make clean` will delete this, and it is recommended that it not be
@@ -299,6 +307,18 @@ The following additional variables can be used to control the behaviour
     default, to enable additional rules without overriding the existing
     ones.
 
+- **`DATAEXT`:**
+  A list of file extensions which signify “data” files during a two‐stage build using `DATADIR`.
+
+- **`FINDDATARULES`:**
+  Rules to use with `find` when searching for data files.
+  By default, these rules are derived from `DATAEXT`.
+
+- **`EXTRAFINDDATARULES`:**
+  The value of this variable is appended to `FINDDATARULES` by
+    default, to enable additional rules without overriding the existing
+    ones.
+
 - **`PARSERS`:**
   A white·space‐separated list of parsers to use (default:
     `$(THISDIR)/parsers/*.xslt`).
@@ -307,6 +327,15 @@ The following additional variables can be used to control the behaviour
   The value of this variable is appended to `PARSERS` by default, to
     enable additional parsers without overriding the existing ones.
 
+- **`PARSERLIBS`:**
+  A white·space‐separated list of parser dependencies (default:
+    `$(THISDIR)/lib/split.xslt`).
+
+- **`EXTRAPARSERLIBS`:**
+  The value of this variable is appended to `PARSERLIBS` by default, to
+    enable additional parser dependencies without overriding the
+    existing ones.
+
 - **`TRANSFORMS`:**
   A white·space‐separated list of transforms to use (default:
     `$(THISDIR)/transforms/*.xslt`).
@@ -315,6 +344,15 @@ The following additional variables can be used to control the behaviour
   The value of this variable is appended to `TRANSFORMS` by default, to
     enable additional transforms without overriding the existing ones.
 
+- **`TRANSFORMLIBS`:**
+  A white·space‐separated list of transform dependencies (default:
+    `$(THISDIR)/lib/serialize.xslt`).
+
+- **`EXTRATRANSFORMLIBS`:**
+  The value of this variable is appended to `TRANSFORMLIBS` by default,
+    to enable additional transform dependencies without overriding the
+    existing ones.
+
 - **`XMLTYPES`:**
   A white·space‐separated list of media types or media type suffixes to
     consider X·M·L (default: `application/xml text/xml +xml`).
@@ -547,6 +585,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 finalization phase, after the main
+    transformation.
 
 - **`transforms/metadata.xslt`:**
   Provides basic `<html:head>` metadata.
@@ -564,7 +604,7 @@ Transforms are used to convert X·M·L files into their final output,
 - **`transforms/serialization.xslt`:**
   Replaces `<书社:serialize-xml>` elements with the (escaped)
     serialized X·M·L of their contents.
-  This replacement happens during the application phase, after most
+  This replacement happens during the finalization phase, after most
     other transformations have taken place.
 
   If a `@with-namespaces` attribute is provided, any name·space nodes
@@ -690,8 +730,8 @@ It is especially useful in combination with output wrapping.
 
 In both cases, attributes from various sources are combined with
   white·space between them.
-Attribute application takes place after all ordinary transforms have
-  completed.
+Attribute application takes place after each stage of the
+  transformation, including after the initial embedding phase.
 
 Both elements ignore attributes in the `xml:` name·space, except for
   `@xml:lang`, which ignores all but the first definition (including