Add EXTRA* variables

[Shushe] / README.markdown

diff --git a/README.markdown b/README.markdown
index 4427c7fed710eb40a5051e147688b77e1f843478..654904ae9eda3ab787fbdc83dc7b001778f5ffda 100644 (file)
--- a/README.markdown
+++ b/README.markdown
@@ -1,6 +1,6 @@
 # ⛩️📰 书社
 
 # ⛩️📰 书社
 

-<b>An X·S·L·T‐based static site generator.</b>
+<b>A make·file for X·M·L.</b>

 
 <dfn>⛩️📰 书社</dfn> aims to make it easy to generate websites with
   X·S·L·T and G·N·U Make.
 
 <dfn>⛩️📰 书社</dfn> aims to make it easy to generate websites with
   X·S·L·T and G·N·U Make.


@@ -18,6 +18,15 @@ It makes things easier by :⁠—
 
 It aims to do this with zero dependencies beyond the programs already
   installed on your computer.
 
 It aims to do this with zero dependencies beyond the programs already
   installed on your computer.

+(On Linux machines, you may need to install `libxml2-utils` to get the
+  commandline programs from `libxml2`.)
+
+**Note:**
+⛩️📰 书社 requires functionality present in G·N·U Make 3.81 (or later)
+  and will not work in previous versions, or other implementations of
+  Make.
+Compatibility with later versions of G·N·U Make is assumed, but not
+  tested.

 
 ## Nomenclature
 
 
 ## Nomenclature
 


@@ -98,6 +107,7 @@ In every case, you may supply your own implementation by overriding the
 - `echo`
 - `file`
 - `find`
 - `echo`
 - `file`
 - `find`

+- `git` (optional; set `GIT=` to disable)

 - `mkdir` (requires support for `-p`)
 - `mv`
 - `od` (requires support for `-t x1`)
 - `mkdir` (requires support for `-p`)
 - `mv`
 - `od` (requires support for `-t x1`)


@@ -159,22 +169,39 @@ The following additional variables can be used to control the behaviour
 
 - **`FINDRULES`:**
   Rules to use with `find` when searching for source files.
 
 - **`FINDRULES`:**
   Rules to use with `find` when searching for source files.

-  The default ignores hidden files, those that start with a period or
-    hyphen‐minus, and those which contain a pipe, buck, percent, or
-    colon.
+  The default ignores files that start with a period or hyphen‐minus
+    and those which contain a hash, buck, percent, asterisk, colon,
+    semi, eroteme, bracket, backslash, or pipe.
+
+- **`EXTRAFINDRULES`:**
+  The value of this variable is appended to `FINDRULES` by default, to
+    enable additional rules without overriding the existing ones.

 
 - **`FINDINCLUDERULES`:**
   Rules to use with `find` when searching for includes (default:
     `$(FINDRULES)`).
 
 
 - **`FINDINCLUDERULES`:**
   Rules to use with `find` when searching for includes (default:
     `$(FINDRULES)`).
 

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

+- **`EXTRAPARSERS`:**
+  The value of this variable is appended to `PARSERS` by default, to
+    enable additional parsers without overriding the existing ones.
+

 - **`TRANSFORMS`:**
   A white·space‐separated list of transforms to use (default:
     `$(THISDIR)/transforms/*.xslt`).
 
 - **`TRANSFORMS`:**
   A white·space‐separated list of transforms to use (default:
     `$(THISDIR)/transforms/*.xslt`).
 

+- **`EXTRATRANSFORMS`:**
+  The value of this variable is appended to `TRANSFORMS` by default, to
+    enable additional transforms without overriding the existing ones.
+

 - **`XMLTYPES`:**
   A white·space‐separated list of media types to consider X·M·L
     (default: `application/xml text/xml`).
 - **`XMLTYPES`:**
   A white·space‐separated list of media types to consider X·M·L
     (default: `application/xml text/xml`).


@@ -207,10 +234,11 @@ Text formats with associated X·S·L·T parsers are wrapped in a H·T·M·L
 Source files whose media type does not have an associated X·S·L·T
   parser are considered “assets” and will not be transformed.
 
 Source files whose media type does not have an associated X·S·L·T
   parser are considered “assets” and will not be transformed.
 

-**☡ For compatibility with this program, source filenames must not
-  contain Ascii whitespace, colons (`:`), pipes (`|`), bucks (`$`),
-  percents (`%`) or control characters, and must not begin with a
-  hyphen‐minus (`-`).**
+**☡ For compatibility with this program, source file·names must not
+  contain Ascii white·space, colons (`:`), semis (`;`), pipes (`|`),
+  bucks (`$`), percents (`%`), hashes (`#`), asterisks (`*`), brackets
+  (`[` or `]`), erotemes (`?`), backslashes (`\`), or control
+  characters, and must not begin with a hyphen‐minus (`-`).**

 The former characters have the potential to conflict with make syntax,
   and a leading hyphen‐minus is confusable for a command‐line argument.
 
 The former characters have the potential to conflict with make syntax,
   and a leading hyphen‐minus is confusable for a command‐line argument.
 


@@ -374,10 +402,32 @@ The following are recommendations on effective creation of
 - Set `@exclude-result-prefixes` on the root `xslt:transform` element
     to reduce the number of declared namespaces in the final result.
 
 - Set `@exclude-result-prefixes` on the root `xslt:transform` element
     to reduce the number of declared namespaces in the final result.
 

-The params `$buildtime`, `$srctime`, and `$path` are available within
-  transforms and are initialized to the current time, the time that the
-  source file was last modified, and the path of the output file within
-  $(DESTDIR).
+## Global Params
+
+The following params are made available globally in parsers and
+  transforms :⁠—
+
+- **`BUILDTIME`:**
+  The current time.
+
+- **`SRCREV`:**
+  The tag or hash of the current commit in the working directory (if
+    `GIT` is defined and `./.git` exists).
+
+- **`SRCTIME`:**
+  The time at which the source file was last modified.
+
+- **`VERSION`:**
+  The tag or hash of the current commit in `THISDIR` (if `GIT` is
+    defined and `$(THISDIR)/.git` exists).
+
+The following params are only available in transforms :⁠—
+
+- **`CATALOG`:**
+  The path of the catalog file (within `BUILDDIR`).
+
+- **`PATH`:**
+  The path of the output file (within `DESTDIR`).

 
 ## Output Wrapping
 
 
 ## Output Wrapping
 


@@ -438,4 +488,4 @@ Source files are licensed under the terms of the <cite>Mozilla Public
   License, version 2.0</cite>.
 For more information, see [LICENSE](./LICENSE).
 
   License, version 2.0</cite>.
 For more information, see [LICENSE](./LICENSE).
 

-[draft-phillips-record-jar-01]: <https://datatracker.ietf.org/doc/html/draft-phillips-record-jar-01>
\ No newline at end of file
+[draft-phillips-record-jar-01]: <https://datatracker.ietf.org/doc/html/draft-phillips-record-jar-01>