Replace GENERATOR and VERSION with THISREV

[Shushe] / README.markdown

diff --git a/README.markdown b/README.markdown
index 0941b52095f1609285389d7663537562abfa57d6..6b4f06ed18627a3a8dc344f94b5595b74bb85ba3 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
 


@@ -93,12 +102,14 @@ In every case, you may supply your own implementation by overriding the
 
 - `awk`
 - `cat`
 
 - `awk`
 - `cat`

+- `cksum`

 - `cp`
 - `date`
 - `echo`
 - `file`
 - `find`
 - `git` (optional; set `GIT=` to disable)
 - `cp`
 - `date`
 - `echo`
 - `file`
 - `find`
 - `git` (optional; set `GIT=` to disable)

+- `ln`

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


@@ -155,31 +166,62 @@ The following additional variables can be used to control the behaviour
   This variable is used to find the ⛩️📰 书社 `lib/` folder, which is
     expected to be in the same location.
 
   This variable is used to find the ⛩️📰 书社 `lib/` folder, which is
     expected to be in the same location.
 

-- **`MAGICDIR`:**
-  The location of the magic files to use (default: `$(THISDIR)/magic`).
+- **`MAGIC`:**
+  A white·space‐separated list of magic files to use (default:
+    `$(THISDIR)/magic/*`).
+
+- **`EXTRAMAGIC`:**
+  The value of this variable is appended to `MAGIC` by default, to
+    enable additional magic files without overriding the existing ones.

 
 - **`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 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.
+  The default ignores files that start with a period or hyphen‐minus,
+    those which end with a cloparen, 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`).
 

+- **`THISREV`:**
+  The current version of ⛩️📰 书社 (default: derived from the current
+    git tag/branch/commit).
+
+- **`SRCREV`:**
+  The current version of the source files (default: derived from the
+    current git tag/branch/commit).
+

 - **`VERBOSE`:**
   If this variable has a value, every recipe instruction will be
     printed when it runs (default: empty).
 - **`VERBOSE`:**
   If this variable has a value, every recipe instruction will be
     printed when it runs (default: empty).


@@ -212,9 +254,12 @@ Source files whose media type does not have an associated X·S·L·T
   contain Ascii white·space, colons (`:`), semis (`;`), pipes (`|`),
   bucks (`$`), percents (`%`), hashes (`#`), asterisks (`*`), brackets
   (`[` or `]`), erotemes (`?`), backslashes (`\`), or control
   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 (`-`).**
+  characters, must not begin with a hyphen‐minus (`-`), and must not
+  end with a cloparen (`)`).**

 The former characters have the potential to conflict with make syntax,
 The former characters have the potential to conflict with make syntax,

-  and a leading hyphen‐minus is confusable for a command‐line argument.
+  a leading hyphen‐minus is confusable for a command‐line argument, and
+  a trailing cloparen [activates a bug in G·N·U Make
+  3.81](https://stackoverflow.com/questions/17148468/capturing-filenames-including-parentheses-with-gnu-makes-wildcard-function#comment24825307_17148894).

 
 ## Parsers
 
 
 ## Parsers
 


@@ -224,16 +269,15 @@ Parsers are used to convert plaintext files into X·M·L trees, as well
 ⛩️📰 书社 comes with some parsers; namely :⁠—
 
 - **`parsers/plain.xslt`:**
 ⛩️📰 书社 comes with some parsers; namely :⁠—
 
 - **`parsers/plain.xslt`:**

-  Wraps `text/plain` contents in a `<html:pre class="plain">` element.
+  Wraps `text/plain` contents in a `<html:pre>` element.

 
 - **`parsers/record-jar.xslt`:**
 
 - **`parsers/record-jar.xslt`:**

-  Converts `text/record-jar` contents into a
-    `<html:div class="record-jar">` of `<html:dl>` elements (one for
-    each record).
+  Converts `text/record-jar` contents into a `<html:div>` of
+    `<html:dl>` elements (one for each record).

 
 - **`parsers/tsv.xslt`:**
 
 - **`parsers/tsv.xslt`:**

-  Converts `text/tab-separated-values` contents into an
-    `<html:table class="tsv">` element.
+  Converts `text/tab-separated-values` contents into an `<html:table>`
+    element.

 
 New ⛩️📰 书社 parsers which target plaintext formats should have an
   `<xslt:template>` element with no `@name` or `@mode` and whose
 
 New ⛩️📰 书社 parsers which target plaintext formats should have an
   `<xslt:template>` element with no `@name` or `@mode` and whose


@@ -299,6 +343,26 @@ It is **strongly recommended** that auxillary templates in parsers be
   namespaced (by `@name` or `@mode`) whenever possible, to avoid
   conflicts between parsers.
 
   namespaced (by `@name` or `@mode`) whenever possible, to avoid
   conflicts between parsers.
 

+### Attributes added during parsing
+
+⛩️📰 书社 will add a few attributes to the output of the parsing step,
+  namely :⁠—
+
+- A `@书社:cksum` attribute on toplevel result elements, giving the
+    `cksum` checksum of the corresponding source file.
+
+- For the elements which result from parsing plaintext `<html:script>`
+    elements :⁠—
+
+  - A `@书社:parsed-by` attribute, giving a space‐separated list of
+      parsers which parsed the node.
+    (Generally, this will be a list of one, but it is possible for the
+      result of a parse to be another plaintext node, which may be
+      parsed by a different parser.)
+
+  - A `@书社:media-type` attribute, giving the identified media type of
+      the plaintext node.
+

 ## Embedding
 
 Documents can be embedded in other documents using a `<书社:link>`
 ## Embedding
 
 Documents can be embedded in other documents using a `<书社:link>`


@@ -384,16 +448,17 @@ The following params are made available globally in parsers and
 - **`BUILDTIME`:**
   The current time.
 
 - **`BUILDTIME`:**
   The current time.
 

+- **`CKSUM`:**
+  The checksum of the source file (⅌ `cksum`).
+

 - **`SRCREV`:**
 - **`SRCREV`:**

-  The tag or hash of the current commit in the working directory (if
-    `GIT` is defined and `./.git` exists).
+  The value of the `SRCREV` variable (if present).

 
 - **`SRCTIME`:**
   The time at which the source file was last modified.
 
 
 - **`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).
+- **`THISREV`:**
+  The value of the `THISREV` variable (if present).

 
 The following params are only available in transforms :⁠—
 
 
 The following params are only available in transforms :⁠—
 


@@ -462,4 +527,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>