Track catalog & magic prereqs and diff for changes

[Shushe] / README.markdown

diff --git a/README.markdown b/README.markdown
index 5b5b84c458c5103e9e748ae29a362255fa84a224..e0a143e5f5ea0fa823630038a616edf6496ec97f 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
 


@@ -91,21 +100,29 @@ In every case, you may supply your own implementation by overriding the
   corresponding (allcaps) variable (e·g, set `MKDIR` to supply your own
   `mkdir` implementation).
 
   corresponding (allcaps) variable (e·g, set `MKDIR` to supply your own
   `mkdir` implementation).
 

+- `awk`

 - `cat`
 - `cat`

+- `cksum`

 - `cp`
 - `cp`

+- `date`

 - `echo`
 - `file`
 - `find`
 - `echo`
 - `file`
 - `find`

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

 - `mkdir` (requires support for `-p`)
 - `mv`
 - `mkdir` (requires support for `-p`)
 - `mv`

+- `od` (requires support for `-t x1`)

 - `printf`
 - `rm`
 - `sed`
 - `sleep`
 - `printf`
 - `rm`
 - `sed`
 - `sleep`

+- `stat`

 - `test`
 - `touch`
 - `tr` (requires support for `-d`)
 - `uuencode` (requires support for `-m` and `-r`)
 - `test`
 - `touch`
 - `tr` (requires support for `-d`)
 - `uuencode` (requires support for `-m` and `-r`)

+- `xargs` (requires support for `-0`)

 - `xmlcatalog` (provided by `libxml2`)
 - `xmllint` (provided by `libxml2`)
 - `xsltproc` (provided by `libxslt`)
 - `xmlcatalog` (provided by `libxml2`)
 - `xmllint` (provided by `libxml2`)
 - `xsltproc` (provided by `libxslt`)


@@ -115,16 +132,32 @@ The following additional variables can be used to control the behaviour
 
 - **`SRCDIR`:**
   The location of the source files (default: `sources`).
 
 - **`SRCDIR`:**
   The location of the source files (default: `sources`).

+  Multiple source directories can be provided, so long as the same
+    file subpath doesn’t exist in more than one of them.

 
 - **`INCLUDEDIR`:**
 
 - **`INCLUDEDIR`:**

-  The location of the source files (default: `sources/includes`).
+  The location of source includes (default: `sources/includes`).

   This can be inside of `SRCDIR`, but needn’t be.
   This can be inside of `SRCDIR`, but needn’t be.

+  Multiple include directories can be provided, so long as the same
+    file subpath doesn’t exist in more than one of them.

 
 - **`BUILDDIR`:**
   The location of the (temporary) build directory (default: `build`).
 
 - **`BUILDDIR`:**
   The location of the (temporary) build directory (default: `build`).

+  `make clean` will delete this, and it is recommended that it not be
+    used for programs aside from ⛩️📰 书社.

 
 - **`DESTDIR`:**
   The location of directory to output files to (default: `public`).
 
 - **`DESTDIR`:**
   The location of directory to output files to (default: `public`).

+  `make install` will overwrite files in this directory which
+    correspond to those in `SRCDIR`.
+  It *will not* touch other files, including those generated from files
+    in `SRCDIR` which have since been deleted.
+
+  Files are first compiled to `$(BUILDDIR)/public` before they are
+    copied to `DESTDIR`, so this folder is relatively quick and
+    inexpensive to re·create.
+  It’s reasonable to simply delete it before every `make install` to
+    ensure stale content is removed.

 
 - **`THISDIR`:**
   The location of the ⛩️📰 书社 `GNUmakefile`.
 
 - **`THISDIR`:**
   The location of the ⛩️📰 书社 `GNUmakefile`.


@@ -133,29 +166,65 @@ 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/*`).

 
 

-- **`FINDOPTS`:**
-  Options to pass to `find` when searching for source files (default:
-    `-LE`).
+- **`EXTRAMAGIC`:**
+  The value of this variable is appended to `MAGIC` by default, to
+    enable additional magic files without overriding the existing ones.

 
 - **`FINDRULES`:**
 
 - **`FINDRULES`:**

-  Rules to use with `find` when searching for source files (default:
-    `-flags -nohidden -and -not -name '.*'`).
+  Rules to use with `find` when searching for source files.
+  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)`).
+
+- **`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`).
 

+- **`GENERATOR`:**
+  The name of the generator program (default: `⛩️📰 书社`).
+
+- **`VERSION`:**
+  The current version of `GENERATOR` (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).


@@ -175,6 +244,8 @@ Supported magic numbers include :⁠—
 - `#!js` for `text/javascript` files
 - `@charset "` for `text/css` files
 - `#!tsv` for `text/tab-separated-values` files
 - `#!js` for `text/javascript` files
 - `@charset "` for `text/css` files
 - `#!tsv` for `text/tab-separated-values` files

+- `%%` for `text/record-jar` files (unregistered; see
+    [[draft-phillips-record-jar-01][]])

 
 Text formats with associated X·S·L·T parsers are wrapped in a H·T·M·L
   `<script>` element whose `@type` gives its media type, and then
 
 Text formats with associated X·S·L·T parsers are wrapped in a H·T·M·L
   `<script>` element whose `@type` gives its media type, and then


@@ -182,18 +253,16 @@ 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 should conform to
-  the following rules :⁠—
-
-- They should not start with a hyphen‐minus.
-  This is to prevent confusion between filenames and options on the
-    commandline.
-
-- They should not contain spaces, colons, percent signs, backticks,
-    question marks, hashes, or backslashes.
-
-In general, filenames should be such that they do not require
-  percent‐encoding in the path component of an i·r·i.
+**☡ 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, 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,
+  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
 


@@ -203,14 +272,20 @@ 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>` element.
+  Wraps `text/plain` contents in a `<html:pre class="plain">` element.
+
+- **`parsers/record-jar.xslt`:**
+  Converts `text/record-jar` contents into a
+    `<html:div class="record-jar">` of `<html:dl>` elements (one for
+    each record).

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

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

 
 

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

 
 - Starts with an appropriately‐namespaced qualified name for a
     `<html:script>` element.
 
 - Starts with an appropriately‐namespaced qualified name for a
     `<html:script>` element.


@@ -230,8 +305,10 @@ For example, the trivial `text/plain` parser is defined as follows :⁠—
 <transform
   xmlns="http://www.w3.org/1999/XSL/Transform"
   xmlns:html="http://www.w3.org/1999/xhtml"
 <transform
   xmlns="http://www.w3.org/1999/XSL/Transform"
   xmlns:html="http://www.w3.org/1999/xhtml"

+  xmlns:书社="urn:fdc:ladys.computer:20231231:Shu1She4"

   version="1.0"
 >
   version="1.0"
 >

+  <书社:id>example:text/plain</书社:id>

   <template match="html:script[@type='text/plain']">
     <html:pre><value-of select="."/></html:pre>
   </template>
   <template match="html:script[@type='text/plain']">
     <html:pre><value-of select="."/></html:pre>
   </template>


@@ -242,10 +319,33 @@ For example, the trivial `text/plain` parser is defined as follows :⁠—
   the set of allowed plaintext file types.
 Multiple such `<xslt:template>` elements may be provided in a single
   parser, for example if the parser supports multiple media types.
   the set of allowed plaintext file types.
 Multiple such `<xslt:template>` elements may be provided in a single
   parser, for example if the parser supports multiple media types.

-
-It is **strongly recommended** that all templates in parsers other than
-  those described above be namespaced (by `@name` or `@mode`), to avoid
-  conflicts between templates in multiple parsers.
+Alternatively, you can set the `@书社:supported-media-types` attribute
+  on the root element of the parser to override media type support
+  detection.
+
+Even when `@书社:supported-media-types` is set, it is a requirement
+  that each parser transform any `<html:script>` elements with a
+  `@type` which matches their registered types into something else.
+Otherwise the parser will be stuck in an endless loop.
+The result tree of applying the transform to the `<html:script>`
+  element will be reparsed (in case any new `<html:script>` elements
+  were added in its subtree), and a `@书社:parsed-by` attribute will be
+  added to each toplevel element in the result.
+The value of this attribute will be the value of the `<书社:id>`
+  toplevel element in the parser.
+
+It is possible for parsers to support zero plaintext types.
+This is useful when targeting specific dialects of X·M·L; parsers in
+  this sense operate on the same basic principles as transforms
+  (described below).
+The major distinction between X·M·L parsers and transforms is where in
+  the process the transformation happens:
+Parsers are applied *prior* to embedding (and can be used to generate
+  embeds); transforms are applied *after*.
+
+It is **strongly recommended** that auxillary templates in parsers be
+  namespaced (by `@name` or `@mode`) whenever possible, to avoid
+  conflicts between parsers.

 
 ## Embedding
 
 
 ## Embedding
 


@@ -270,12 +370,29 @@ Embedding takes place after parsing but before transformation, so
   and update them accordingly; it will signal an error if the
   dependencies are recursive.
 
   and update them accordingly; it will signal an error if the
   dependencies are recursive.
 

+## Output Redirection
+
+By default, ⛩️📰 书社 installs files to the same location in `DESTDIR`
+  as they were placed in their `SRCDIR`.
+This behaviour can be customized by setting the `@书社:destination`
+  attribute on the root element, whose value can give a different path.
+This attribute is read after parsing, but before transformation (where
+  it is silently dropped).
+

 ## Transforms
 
 Transforms are used to convert X·M·L files into their final output,
   after all necessary parsing and embedding has taken place.
 ⛩️📰 书社 comes with some transforms; namely :⁠—
 
 ## Transforms
 
 Transforms are used to convert X·M·L files into their final output,
   after all necessary parsing and embedding has taken place.
 ⛩️📰 书社 comes with some transforms; namely :⁠—
 

+- **`transforms/attributes.xslt`:**
+  Applies transforms to the children of any `<书社:apply-attributes>`
+    elements, and then applies the attributes of the
+    `<书社:apply-attributes>` to each result child, replacing the
+    element with the result.
+  This is useful in combination with image embeds to apply alt‐text to
+    the resulting `<html:img>`.
+

 - **`transforms/asset.xslt`:**
   Converts `<html:object>` elements which correspond to recognized
     media types into the appropriate H·T·M·L elements, and deletes
 - **`transforms/asset.xslt`:**
   Converts `<html:object>` elements which correspond to recognized
     media types into the appropriate H·T·M·L elements, and deletes


@@ -284,7 +401,7 @@ Transforms are used to convert X·M·L files into their final output,
 
 - **`transforms/metadata.xslt`:**
   Provides basic `<html:head>` metadata.
 
 - **`transforms/metadata.xslt`:**
   Provides basic `<html:head>` metadata.

-  This metadata is generated from `<html:meta>` elements with one o.
+  This metadata is generated from `<html:meta>` elements with one of

     the following `@itemprop` attributes :⁠—
 
   - **`urn:fdc:ladys.computer:20231231:Shu1She4:title`:**
     the following `@itemprop` attributes :⁠—
 
   - **`urn:fdc:ladys.computer:20231231:Shu1She4:title`:**


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

+## Global Params
+
+The following params are made available globally in parsers and
+  transforms :⁠—
+
+- **`BUILDTIME`:**
+  The current time.
+
+- **`CKSUM`:**
+  The checksum of the source file (⅌ `cksum`).
+
+- **`GENERATOR`:**
+  The value of the `GENERATOR` variable (if present).
+
+- **`SRCREV`:**
+  The value of the `SRCREV` variable (if present).
+
+- **`SRCTIME`:**
+  The time at which the source file was last modified.
+
+- **`VERSION`:**
+  The value of the `VERSION` variable (if present).
+
+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
 
 ⛩️📰 书社 will wrap the final output of the transforms in appropriate
 ## Output Wrapping
 
 ⛩️📰 书社 will wrap the final output of the transforms in appropriate


@@ -332,7 +480,7 @@ In addition to being called with the transform result, each of these
   modes will additionally be called with a `<xslt:include>` element
   corresponding to each transform.
 If a transform has a `<书社:id>` top‐level element whose value is an
   modes will additionally be called with a `<xslt:include>` element
   corresponding to each transform.
 If a transform has a `<书社:id>` top‐level element whose value is an

-  i·r·i, its `<xslt:import>` element will have a corresponding
+  i·r·i, its `<xslt:include>` element will have a corresponding

   `@书社:id` attribute.
 This mechanism can be used to allow transforms to insert content
   without matching any elements in the result; for example, the
   `@书社:id` attribute.
 This mechanism can be used to allow transforms to insert content
   without matching any elements in the result; for example, the


@@ -365,3 +513,5 @@ Output wrapping can be entirely disabled by adding a
 Source files are licensed under the terms of the <cite>Mozilla Public
   License, version 2.0</cite>.
 For more information, see [LICENSE](./LICENSE).
 Source files are licensed under the terms of the <cite>Mozilla Public
   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>