X-Git-Url: https://git.ladys.computer/Shushe/blobdiff_plain/5031f269c8440435da01151f6a08ada632ae4b5f..a555040fdebc4432aee0c167a89e74ed1378f735:/README.markdown?ds=sidebyside

diff --git a/README.markdown b/README.markdown
index 4ce9994..d4399e3 100644
--- a/README.markdown
+++ b/README.markdown
@@ -1,5 +1,5 @@
 <!--
-SPDX-FileCopyrightText: 2024 Lady <https://www.ladys.computer/about/#lady>
+SPDX-FileCopyrightText: 2024, 2025 Lady <https://www.ladys.computer/about/#lady>
 SPDX-License-Identifier: CC0-1.0
 -->
 # ā›©šŸ“° ä¹¦ē¤¾
@@ -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,44 @@ 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.
+
+- **`FINDFILTERONLY`:**
+  A semicolonā€separated list of regular expressions, at least one of which the paths for sources and includes are required to match, unless empty (default: empty).
+
+- **`FINDFILTEROUT`:**
+  A semicolonā€separated list of regular expressions, each of which matches paths that should _not_ be considered sources or includes (default: empty).
+
+- **`FINDINCLUDEFILTERONLY`:**
+  A semicolonā€separated list of regular expressions, at least one of which the paths for includes are required to match, unless empty (default: empty).
+
+  Note that only paths which already match `FINDFILTERONLY` are considered.
+
+- **`FINDINCLUDEFILTEROUT`:**
+  A semicolonā€separated list of regular expressions, each of which matches paths that should _not_ be considered includes, but may still be considered sources (default: empty).
+
+- **`FINDFILTERONLYEXTENDED`:**
+  If nonĀ·empty, `FINDFILTERONLY` is an extended regular expression; otherwise, it is basic (default: empty).
+
+- **`FINDFILTEROUTEXTENDED`:**
+  If nonĀ·empty, `FINDFILTEROUT` is an extended regular expression; otherwise, it is basic (default: matches `FINDFILTERONLYEXTENDED`).
+
+- **`FINDINCLUDEFILTERONLYEXTENDED`:**
+  If nonĀ·empty, `FINDINCLUDEFILTERONLY` is an extended regular expression; otherwise, it is basic (default: matches `FINDFILTERONLYEXTENDED`).
+
+- **`FINDINCLUDEFILTEROUTEXTENDED`:**
+  If nonĀ·empty, `FINDINCLUDEFILTEROUT` is an extended regular expression; otherwise, it is basic (default: `1` if either `FINDFILTEROUTEXTENDED` or `FINDINCLUDEFILTERONLYEXTENDED` is nonĀ·empty).
+
 - **`PARSERS`:**
   A whiteĀ·spaceā€separated list of parsers to use (default:
     `$(THISDIR)/parsers/*.xslt`).
@@ -307,6 +353,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 +370,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 +611,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 +630,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
@@ -618,11 +684,6 @@ 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
 
 Provided at least one toplevel result element belongs to the HĀ·TĀ·MĀ·L
@@ -695,8 +756,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