Add DATAOPTS

[Shushe] / README.markdown

diff --git a/README.markdown b/README.markdown
index 503a16338dda83163e59c655e8c9a02cf00d66ec..70a9730182b25a89b8542b8a8bed91a3aa875931 100644 (file)
--- 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
 -->
 # ⛩📰 书社
 SPDX-License-Identifier: CC0-1.0
 -->
 # ⛩📰 书社


@@ -307,6 +307,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`.
 


@@ -319,6 +325,32 @@ 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.
 

+- **`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`).
 - **`PARSERS`:**
   A white·space‐separated list of parsers to use (default:
     `$(THISDIR)/parsers/*.xslt`).


@@ -585,7 +617,7 @@ 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.
     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 application phase, after the main
+  This conversion happens during the finalization phase, after the main

     transformation.
 
 - **`transforms/metadata.xslt`:**
     transformation.
 
 - **`transforms/metadata.xslt`:**


@@ -604,7 +636,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.
 - **`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
     other transformations have taken place.
 
   If a `@with-namespaces` attribute is provided, any name·space nodes


@@ -730,8 +762,8 @@ It is especially useful in combination with output wrapping.
 
 In both cases, attributes from various sources are combined with
   white·space between them.
 
 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
 
 Both elements ignore attributes in the `xml:` name·space, except for
   `@xml:lang`, which ignores all but the first definition (including