Allow ⛩️📰 书社 to produce plain text

[Shushe] / README.markdown

diff --git a/README.markdown b/README.markdown
index 9d518896eaed97d4e8903bde4c9390a71c1deda3..7c663be305086a76c6d33937a012c7eb339e4ce9 100644 (file)
--- a/README.markdown
+++ b/README.markdown
@@ -1,3 +1,7 @@
+<!--
+SPDX-FileCopyrightText: 2024 Lady <https://www.ladys.computer/about/#lady>
+SPDX-License-Identifier: CC0-1.0
+-->

 # ⛩️📰 书社
 
 <b>A make·file for X·M·L.</b>
 # ⛩️📰 书社
 
 <b>A make·file for X·M·L.</b>


@@ -69,9 +73,13 @@ Compilation involves the following steps :⁠—
 5. ⛩️📰 书社 uses the dependency tree to establish prerequisites for
     each output file.
 
 5. ⛩️📰 书社 uses the dependency tree to establish prerequisites for
     each output file.
 

-6. ⛩️📰 书社 compiles each output file to `build/public`.
+6. ⛩️📰 书社 compiles each output file to `build/result`.

 
 

-7. ⛩️📰 书社 copies the output files to `public`.
+7. ⛩️📰 书社 symlinks most output files from `build/result` to
+     `build/public`, but it does some additional processing instead on
+     those which indicate a non‐X·M·L desired final output form.
+
+8. ⛩️📰 书社 copies the final resulting files to `public`.

 
 You can use `make list` to list each identified source file or include
   alongside its computed type and dependencies.
 
 You can use `make list` to list each identified source file or include
   alongside its computed type and dependencies.


@@ -102,12 +110,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`)


@@ -120,6 +130,7 @@ In every case, you may supply your own implementation by overriding the
 - `touch`
 - `tr` (requires support for `-d`)
 - `uuencode` (requires support for `-m` and `-r`)
 - `touch`
 - `tr` (requires support for `-d`)
 - `uuencode` (requires support for `-m` and `-r`)

+- `uudecode` (requires support for `-m` and `-r`)

 - `xargs` (requires support for `-0`)
 - `xmlcatalog` (provided by `libxml2`)
 - `xmllint` (provided by `libxml2`)
 - `xargs` (requires support for `-0`)
 - `xmlcatalog` (provided by `libxml2`)
 - `xmllint` (provided by `libxml2`)


@@ -164,31 +175,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).


@@ -221,9 +263,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
 


@@ -233,16 +278,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


@@ -308,6 +352,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>`


@@ -324,6 +388,8 @@ Embeds are replaced with the parsed contents of a file, unless the file
   is an asset, in which case an `<html:object>` element is produced
   instead (with the contents of the asset file provided as a base64
   `data:` u·r·i).
   is an asset, in which case an `<html:object>` element is produced
   instead (with the contents of the asset file provided as a base64
   `data:` u·r·i).

+Embed replacements will be given a `@书社:identifier` attribute whose
+  value will match the `@xlink:href` of the embed.

 
 Embedding takes place after parsing but before transformation, so
   parsers are able to generate their own embeds.
 
 Embedding takes place after parsing but before transformation, so
   parsers are able to generate their own embeds.


@@ -346,14 +412,6 @@ 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 :⁠—
 
   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


@@ -368,8 +426,8 @@ Transforms are used to convert X·M·L files into their final output,
   - **`urn:fdc:ladys.computer:20231231:Shu1She4:title`:**
     Provides the title of the page.
 
   - **`urn:fdc:ladys.computer:20231231:Shu1She4:title`:**
     Provides the title of the page.
 

-  ⛩️📰 书社 automatically encapsulates embeds so that their metadata
-    does not propogate up to the embedding document.
+  ⛩️📰 书社 automatically encapsulates H·T·M·L embeds so that their
+    metadata does not propogate up to the embedding document.

   To undo this behaviour, remove the `@itemscope` and `@itemtype`
     attributes from the embed during the transformation phase.
 
   To undo this behaviour, remove the `@itemscope` and `@itemtype`
     attributes from the embed during the transformation phase.
 


@@ -393,16 +451,21 @@ 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`).
+
+- **`IDENTIFIER`:**
+  The ⛩️📰 书社 identifier of the source file (a u·r·i beginning with
+    `about:shushe`).
+

 - **`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 :⁠—
 


@@ -464,11 +527,52 @@ This mechanism can be used to allow transforms to insert content
 Output wrapping can be entirely disabled by adding a
   `@书社:disable-output-wrapping` attribute to the top‐level element in
   the result tree.
 Output wrapping can be entirely disabled by adding a
   `@书社:disable-output-wrapping` attribute to the top‐level element in
   the result tree.

+It will not be performed on outputs whose root elements are
+  `<书社:raw-text>` or `<书社:base64-binary>` (described below).
+
+## Applying Attributes
+
+The `<书社:apply-attributes>` element will apply any attributes on the
+  element to the element(s) it wraps.
+It is especially useful in combination with embeds.
+
+The `<书社:apply-attributes-to-root>` element will apply any attributes
+  on the element to the root node of the final transformation result.
+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.
+
+Both elements ignore attributes in the `xml:` namespace, except for
+  `@xml:lang`, which ignores all but the first definition (including
+  any already present on the root element).
+On H·T·M·L and S·V·G elements, `@lang` has the same behaviour as
+  `@xml:lang`.
+
+## Other Kinds of Output
+
+There are a few special elements in the `书社:` namespace which, if
+  they appear as the toplevel element in a transformation result, cause
+  ⛩️📰 书社 to produce something other than an X·M·L file.
+They are :⁠—
+
+- **`<书社:raw-text>`:**
+  A plaintext (U·T·F‐8) file will be produced from the text nodes in
+    the transformation result.
+
+- **`<书社:base64-binary>`:**
+  The text nodes in the transformation result will, after removing all
+    Ascii whitespace, be treated as a Base·64 string, which is then
+    decoded.

 
 ## 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).
+This repository conforms to [REUSE][].
+
+Most source files are licensed under the terms of the <cite>Mozilla
+  Public License, version 2.0</cite>.

 
 

+[REUSE]: <https://reuse.software/spec/>

 [draft-phillips-record-jar-01]: <https://datatracker.ietf.org/doc/html/draft-phillips-record-jar-01>
 [draft-phillips-record-jar-01]: <https://datatracker.ietf.org/doc/html/draft-phillips-record-jar-01>