Stylistic readme edits

[Shushe] / README.markdown

<!--
SPDX-FileCopyrightText: 2024, 2025, 2026 Lady <https://www.ladys.computer/about/#lady>
SPDX-License-Identifier: CC0-1.0
-->
# ⛩📰 书社

<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.
It is consequently only a good choice for people who like X·S·L·T and
  G·N·U Make and wish it were easier to make websites with them.

It makes things easier by :⁠—

- Automatically identifying source files and characterizing them by
    type (X·M·L, text, or asset).

- Parsing supported text types into X·M·L trees.

- Enabling easy inclusion of source files within each other.

It aims to do this with zero dependencies beyond the programs already
  installed on your computer†.

† Assuming an operating system with a fairly featureful, and
  Posix‐compliant, development setup (e·g, Macintosh ≥ version 10.8).
In fact, on Linux you will probably need to install a few programs:
  `libxml2-utils`, `xsltproc`, `sharutils`, and `pax`.

## Nomenclature

<i lang="cmn-Hans">书社</i> is a Chinese word meaning “publishing
  house”.

The first character, <i lang="cmn-Hans">书</i>, is the simplified form
  of “document”.

The second character, <i lang="cmn-Hans">社</i>, contemporarily means
  “association”, but historically referred to the god of the soil and
  related altars or festivities.
In Japanese, it is an alternate spelling for <i lang="ja">やしろ</i>,
  the word for “Shinto shrine”.

The name <i lang="cmn-Hans">书社</i> was chosen to play on this pun, as
  it is intended as a publishing program for webshrines.

In Ascii environments, ⛩📰 书社 should be written `Shushe`, following
  the pinyin transliteration.

## Prerequisites

In most cases, ⛩📰 书社 aims to require only functionality which is
  present in all Posix‐compliant (`POSIX.1-2001`) operating systems.
There are a few exceptions.
Details on particular programs are given below; if a program is not
  listed, it is assumed that any Posix‐compliant implementation will
  work.

### `diff`

This is a Posix utility, but ⛩📰 书社 depends on functionality
  introduced after `POSIX.1-2001` (the `-u` option, introduced in
  `POSIX.1-2008`).
Macintosh systems somewhat interestingly implement this option
  correctly in legacy mode (`COMMAND_MODE=legacy`) but incorrectly by
  default (despite claiming `POSIX.1-2008` conformance for this
  utility).
[Note this erroneous comment claiming nanosecond & timezone are
  extensions rather than standardized.][rdar-92753335]
Despite this, the default Macintosh implementation will still work with
  ⛩📰 书社, with the caveat that the timestamp will only include a
  fractional component when a Posix‐compliant (e·g, Macintosh legacy or
  G·N·U) implementation is used.

### `file`

This is a Posix utility, but it was considered optional in
  `POSIX.1-2001` (altho it was made mandatory in `POSIX.1-2008`) and
  ⛩📰 书社 currently depends on unspecified behaviour.
It requires support for the following additional options :⁠—

- **`-C`**, when supplied with `-m`, must be useable to compile a
    `.mgc` magicfile for use with future invocations of `file`.

- **`--files-from`** must be useable to provide a file that `file`
    should read file·names from, and `-` must be useable in this
    context to specify the standard input.

- **`--mime-type`** must cause `file` to print the internet media type
    of the file with no charset parameter.

- **`--separator`** must be useable to set the separator that `file`
    uses to separate file names from types.

These options are implemented by the [Fine Free File Command][F3C],
  which is used by most operating systems.

### `git`

This is not a Posix utility.
Usage of `git` is optional, but recommended (and activated by default).
To disable it, set `GIT=`.

### `make`

This is a Posix utility, but it is considered an optional Software
  Development utility and ⛩📰 书社 currently depends on unspecified
  behaviour.
⛩📰 书社 requires specifically the G·N·U version of `make`, and
  depends on functionality present in version 3.81 or later.
It is not expected to work in previous versions, or with other
  implementations of Make.

### `pax`

This is a Posix utility, but it is not included in the Linux Standard
  Base or installed by default in many distributions.
⛩📰 书社 only requires support for the `ustar` format.

### `uudecode` and `uuencode`

These are Posix utilities, but they were considered optional in
  `POSIX.1-2001` (altho they are made mandatory in `POSIX.1-2008`) and
  they are not included in the Linux Standard Base or installed by
  default in many distributions.
The G·N·U [Sharutils][] package provides one implementation.

### `xmlcatalog` and `xmllint`

These are not a Posix utilities.
They are a part of `libxml2`, but may need to be installed separately
  on some platforms (e·g by the name `libxml2-utils`).

### `xsltproc`

This is not a Posix utility.
It is a part of `libxslt`, but may need to be installed separately on
  some platforms.

## Basic Usage

Place source files in `sources/` and run `make install` to compile
  the result to `public/`.
Compilation involves the following steps :⁠—

1. ⛩📰 书社 compiles all of the magic files in `magic/` into a single
    file, `build/magic.mgc`.

2. ⛩📰 书社 processes all of the parsers in `parsers/` and determines
    the list of supported plaintext types.

3. ⛩📰 书社 identifies all of the source files and includes and uses
    `build/magic.mgc` to classify them by media type.

4. ⛩📰 书社 parses all plaintext and X·M·L source files and includes
    and then builds a dependency tree between them.

5. ⛩📰 书社 uses the dependency tree to establish prerequisites for
    each output file.

6. ⛩📰 书社 compiles each output file to `build/result`.

7. ⛩📰 书社 copies 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.
As this is a Make‐based program, steps will only be run if the
  corresponding buildfile or output file is older than its
  prerequisites.

## Name·spaces

The ⛩📰 书社 name·space is `urn:fdc:ladys.computer:20231231:Shu1She4`.

This document uses a few name·space prefixes, with the following
  meanings :⁠—

|     Prefix | Expansion                                     |
| ---------: | :-------------------------------------------- |
| `catalog:` | `urn:oasis:names:tc:entity:xmlns:xml:catalog` |
|    `exsl:` | `http://exslt.org/common`                     |
| `exslstr:` | `http://exslt.org/strings`                    |
|    `html:` | `http://www.w3.org/1999/xhtml`                |
|     `rdf:` | `http://www.w3.org/1999/02/22-rdf-syntax-ns#` |
|     `svg:` | `http://www.w3.org/2000/svg`                  |
|   `xlink:` | `http://www.w3.org/1999/xlink`                |
|    `xslt:` | `http://www.w3.org/1999/XSL/Transform`        |
|    `书社:` | `urn:fdc:ladys.computer:20231231:Shu1She4`    |

## Setup and Configuration

⛩📰 书社 depends on the following programs to run.
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).

- `awk`
- `cat`
- `cd`
- `cksum`
- `cp`
- `date`
- `diff`
- `file`
- `find`
- `git` (optional; set `GIT=` to disable)
- `grep`
- `ln`
- `mkdir`
- `mv`
- `od`
- `pax` (only when generating archives)
- `printf`
- `rm`
- `sed`
- `sleep`
- `test`
- `touch`
- `tr`
- `uuencode`
- `uudecode`
- `xargs`
- `xmlcatalog` (provided by `libxml2`)
- `xmllint` (provided by `libxml2`)
- `xsltproc` (provided by `libxslt`)

The following additional variables can be used to control the behaviour
  of ⛩📰 书社 :⁠—

- **`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`:**
  The location of source includes (default: `sources/includes`).
  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.

- **`DATADIR`:**
  If set to the location of a directory, ⛩📰 书社 will run a two‐stage
    build.
  In the first stage, only files in `SRCDIR` which match
    `FINDDATARULES` (see below) will be built, with files in `DATADIR`
    serving as includes.
  In the second stage, the remaining files in `SRCDIR` will be built,
    with the files built during the first stage, in addition to any
    files in `INCLUDEDIR`, serving as includes.
  Files built during the first stage are copied into `DESTDIR`
    alongside those from the second stage when installing.

  This functionality is intended for sites where the bulk of the site
    can be built from a few data files which are expensive to create.

- **`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`).
  `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, assuming copies are quick on your
    file·system.

- **`THISDIR`:**
  The location of the ⛩📰 书社 `GNUmakefile`.
  This should be set automatically when calling Make and shouldn¦t ever
    need to be set manually.
  This variable is used to find the ⛩📰 书社 `lib/` folder, which is
    expected to be in the same location.

- **`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 (default: empty).

- **`FINDRULES`:**
  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.
  It is important that these rules not produce any output, as anything
    printed to `stdout` will be considered a result of the find.

- **`EXTRAFINDRULES`:**
  The value of this variable is appended to `FINDRULES` by default, to
    enable additional rules without overriding the existing ones
    (default: empty).

- **`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 (default: empty).

- **`DATAOPTS`:**
  Additional options to use when calling Make during the first stage of
    a two‐stage build using `DATADIR` (default: empty).

  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 twice‐quoted.

- **`DATAEXT`:**
  A list of file extensions which signify “data” files during a
    two‐stage build using `DATADIR`  (default: `rdf`).

- **`FINDDATARULES`:**
  Rules to use with `find` when searching for data files.
  By default, these rules are derived from `DATAEXT`.

- **`EXTRAFINDDATARULES`:**
  The value of this variable is appended to `FINDDATARULES` by
    default, to enable additional rules without overriding the existing
    ones (default: empty).

- **`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`).

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

- **`PARSERLIBS`:**
  A white·space‐separated list of parser dependencies (default:
    `$(THISDIR)/lib/split.xslt`).

- **`EXTRAPARSERLIBS`:**
  The value of this variable is appended to `PARSERLIBS` by default, to
    enable additional parser dependencies without overriding the
    existing ones (default: empty).

- **`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
    (default: empty).

- **`TRANSFORMLIBS`:**
  A white·space‐separated list of transform dependencies (default:
    `$(THISDIR)/lib/serialize.xslt`).

- **`EXTRATRANSFORMLIBS`:**
  The value of this variable is appended to `TRANSFORMLIBS` by default,
    to enable additional transform dependencies without overriding the
    existing ones (default: empty).

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

- **`FINALIZE`:**
  A program to run on (unspecial) X·M·L files after they are
    transformed (default: `xmllint --nonet --nsclean`).
  This variable can be used for postprocessing.

- **`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).

- **`QUIET`:**
  If this variable has a value, informative messages will not be
    printed (default: empty).
  Informative messages print to stderr, not stdout, so disabling them
    usually shouldn’t be necessary.
  This does not (cannot) disable messages from Make itself, for which
    the `-s`, `--silent` ∕ `--quiet` Make option is more likely to be
    useful.

- **`VERBOSE`:**
  If this variable has a value, every recipe instruction will be
    printed when it runs (default: empty).
  This is helpful for debugging, but typically too noisy for general
    usage.

## Source Files

Source files may be placed in `SRCDIR` in any manner; the file
  structure used there will match the output.
The type of source files is _not_ determined by file extension, but
  rather by magic number; this means that files **must** begin with
  something recognizable.
Supported magic numbers include :⁠—

- `<?xml` for `application/xml` 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
  passed to the parser to process.
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 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 commandline argument, and a
  trailing cloparen [activates a bug in G·N·U Make
  3.81][so-17148468-comment].

## Parsers

Parsers are used to convert plaintext files into X·M·L trees, as well
  as convert plaintext formats which are already included inline in
  existing source X·M·L documents.
⛩📰 书社 comes with some parsers; namely :⁠—

- **`parsers/plain.xslt`:**
  Wraps `text/plain` contents in a `<html:pre>` element.

- **`parsers/record-jar.xslt`:**
  Converts `text/record-jar` contents into a `<html:div>` of
    `<html:dl>` elements (one for each record).

- **`parsers/tsv.xslt`:**
  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
  `@match` attribute…

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

- Follows this with the string `[@type=`.

- Follows this with a quoted string giving a media type supported by
    the parser.
  Media type parameters are _not_ supported.

- Follows this with the string `]`.

For example, the trivial `text/plain` parser is defined as follows :⁠—

```xml
<?xml version="1.0"?>
<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"
>
  <书社:id>example:text/plain</书社:id>
  <template match="html:script[@type='text/plain']">
    <html:pre><value-of select="."/></html:pre>
  </template>
</transform>
```

⛩📰 书社 will scan the provided parsers for this pattern to determine
  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.
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.

Parsers **should** have an `<书社:id>` and, if present, it **must** be
  unique.

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 auxiliary templates in parsers be
  name·spaced (by `@name` or `@mode`) whenever possible, to avoid
  conflicts between parsers.

### Attributes added during parsing

⛩📰 书社 will add a few attributes to elements which result from
  parsing plaintext `<html:script>` elements.
These include :⁠—

- 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.

### Parsed metadata

It is possible to extract metadata from a document at the same time as
  it is being parsed.
This is done by creating result elements in the `书社:about` mode;
  these should be R·D·F property elements which apply to the conceptual
  entity that is the document being parsed.

During transformation, metadata for the file with identifier `$FILE`
  can be read from the children of
  `$书社:about//*[@rdf:about=$FILE]/nie:interpretedAs/*`.

## 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).

Multiple destinations can be provided if the same file should be output to multiple places.
The file is retransformed each time, with the value of the `DESTINATION` global param set appropriately.

## Embedding

Documents can be embedded in other documents using a `<书社:link>`
  element with `@xlink:show="embed"` and an `@xlink:actuate` which is
  absent or `"none"`.
The `@xlink:href`s of these elements should have the format
  `about:shushe?source=<path>`, where `<path>` provides the path to the
  file within `SRCDIR`.
Includes, which do not generate outputs of their own but may still be
  freely embedded, instead use the format
  `about:shushe?include=<path>`, where `<path>` provides the path
  within `INCLUDEDIR`.
If `<path>` indicates a directory and ends with a slash (`/`),
  everything within that directory will be embedded.

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).
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.
⛩📰 书社 is able to detect the transitive embed dependencies of files
  and update them accordingly; it will signal an error if the
  dependencies are recursive.

### Attributes added during expansion

⛩📰 书社 will add a few attributes to toplevel result elements, both
  in the main document and any embedded documents, during the expansion
  phase prior to the main transformation.
These include :⁠—

- A `@书社:cksum` attribute giving the `cksum` checksum of the
    corresponding source file.

- A `@书社:mtime` attribute giving the last modified time of the
    corresponding source file.

- A `@书社:identifier` attribute giving the ⛩📰 书社 identifier
    (i·e, starting with `about:shushe?`) of the corresponding source
    file.

- For elements in the `html` namespace, an `itemscope` attribute and an
    `itemtype` attribute with a value of
    `urn:fdc:ladys.computer:20231231:Shu1She4:document` (for the main
    document) or `urn:fdc:ladys.computer:20231231:Shu1She4:embed` (for
    embedded documents).
  These attributes are used to scope any nested `<html:meta>` elements
    with `@itemprop` attributes to their containing documents.

## Soft Dependencies

When a file depends only on the metadata of another file, and not its
  contents, it can be added as a soft dependency rather than an embed.
Soft dependencies are indicated using a `<书社:link>` element with an
  `@xlink:show` of `"other"`, `"none"`, or absent, and an
  `@xlink:actuate` which is absent or `"none"`.
A change to a soft dependency requires a file to be rebuilt, but no
  embedding occurs automatically.
Because there is no automatic embedding, soft dependencies are allowed
  to be recursive.

The `@xlink:href`s of soft dependency `<书社:link>`s are processed in
  exactly the same fashion as embeds, described above.

If the value of `@xlink:show` is `"other"`, the soft dependency is
  transitive.
Any dependencies of the indicated file which have a `@name` which
  matches that of the referencing `<书社:link>` element will also be
  treated as soft dependencies.
If no `@name` is given, it is treated as the empty string.

When a document is embedded directly, all of its soft dependencies are
  also treated as soft dependencies of the embedding object.
However, a document is embedded in a transitive soft dependency, the
  embed is treated exactly as tho it were itself a transitive soft
  dependency.
That means it must have a matching `@name` to be included, and
  like·wise for any embeds or soft dependencies it contains.

If the value of `@xlink:show` is `"none"` or absent, the soft
  dependency is not transitive and its own dependencies are not
  checked.

## 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/asset.xslt`:**
  Converts `<html:object>` elements which correspond to recognized
    media types into the appropriate H·T·M·L elements, and deletes
    `<html:style>` elements from the body of the document while
    transferring them to the head.
  This conversion happens during the finalization phase, after the main
    transformation.

- **`transforms/expansion.xslt`:**
  Performs embedding, as described above.

- **`transforms/metadata.xslt`:**
  Provides basic `<html:head>` metadata.
  This metadata is generated from `<html:meta>` elements with one of
    the following `@itemprop` attributes :⁠—

  - **`urn:fdc:ladys.computer:20231231:Shu1She4:title`:**
    Provides the title of the page.

  ⛩📰 书社 automatically encapsulates H·T·M·L embeds so that their
    metadata does not propagate up to the embedding document.
  To undo this behaviour, remove the `@itemscope` and `@itemtype`
    attributes from the embed during the transformation phase.

- **`transforms/serialization.xslt`:**
  Replaces `<书社:serialize-xml>` elements with the (escaped)
    serialized X·M·L of their contents.
  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
    on the toplevel serialized elements whose U·R·I’s correspond to the
    definitions of the provided prefixes, as defined for the
    `<书社:serialize-xml>` element, will be declared using name·space
    attributes on the serialized elements.
  Otherwise, only name·space nodes which _differ_ from the definitions
    on the `<书社:serialize-xml>` element will be declared.
  The string `#default` may be used to represent the default
    name·space.
  Multiple prefixes may be provided, separated by white·space.

  When it comes to name·spaces used internally by ⛩📰 书社, the
    prefix used by ⛩📰 书社 may be declared _in addition to_ the
    prefix(es) used in the source document(s).
  It is not possible to selectively only declare one prefix for a
    name·space to the exclusion of others.

  `<书社:raw-output>` elements may be used inside of
    `<书社:serialize-xml>` elements to inject raw output into the
    serialized X·M·L.

The following are recommendations on effective creation of
  transforms :⁠—

- Make template matchers as specific as possible.
  It is likely an error if two transforms have templates which match
    the same element (unless the templates have different priority).

- Name·space templates (with `@name` or `@mode`) whenever possible.

- Set `@exclude-result-prefixes` on the root `xslt:transform` element
    to reduce the number of declared name·spaces in the final result.

## Global Params

The following params are made available globally in parsers and
  transforms :⁠—

- **`BUILDTIME`:**
  The current time.

- **`IDENTIFIER`:**
  The ⛩📰 书社 identifier of the source file (a u·r·i beginning with
    `about:shushe`).

- **`SRCREV`:**
  The value of the `SRCREV` variable (if present).

- **`THISREV`:**
  The value of the `THISREV` variable (if present).

In transforms, the following params are additionally available :⁠—

- **`DESTINATION`:**
  The destination being targeted by this transform.

- **`书社:about`:**
  R·D·F metadata about all of the documents ⛩📰 书社 knows about.
  Use `$书社:about//*[@rdf:about=$IDENTIFIER]` to get the metadata for
    the current document.

- **`书社:source`:**
  The parsed source document being transformed, prior to any expansion.

- **`书社:expansion`:**
  The document after the all embeds have been expanded.
  Unavailable during the `书社:expand` stage.

- **`书社:result`:**
  The document after the main set of transformations have been applied.
  Only available during the `书社:finalize` stage, where it is used to
    apply output wrapping and other clean·up.

## Output Wrapping

Provided at least one toplevel result element belongs to the H·T·M·L
  namespace, ⛩📰 书社 will wrap the final output of the transforms in
  appropriate `<html:html>` and `<html:body>` elements, so it is not
  necessary for transforms to do this explicitly.
If a toplevel result element _is_ a `<html:html>` and `<html:body>`
  element, it will be merged with the one that ⛩📰 书社 creates.
Consequently, wrapping the result in a `<html:body>` element can be
  used to enable wrapping for non‐H·T·M·L content, when desired.

As a part of this process, after performing the initial transform
  ⛩📰 书社 will match in the following modes to fill in areas of the
  wrapper :⁠—

- **`书社:header`:**
  The result of matching in this mode is prepended into the
    `<html:body>` of the output (before the transformation result).

- **`书社:footer`:**
  The result of matching in this mode is appended into the
    `<html:body>` of the output (after the transformation result).

- **`书社:metadata`:**
  The result of matching in this mode is inserted into the
    `<html:head>` of the output.

The document being matched will contain the full transform result
  prior to wrapping as well as an `<书社:id>` element for each
  transform.
The latter elements can be matched to enable transforms to provide
  content _without_ matching any elements in the result; for example,
  the following transform adds a link to a stylesheet to the
  `<html:head>` of every page :⁠—

```xml
<?xml version="1.0"?>
<transform
  xmlns="http://www.w3.org/1999/XSL/Transform"
  xmlns:html="http://www.w3.org/1999/xhtml"
  xmlns:xslt="http://www.w3.org/1999/XSL/Transform"
  xmlns:书社="urn:fdc:ladys.computer:20231231:Shu1She4"
  exclude-result-prefixes="书社"
  version="1.0"
>
  <书社:id>example:add-stylesheet-links.xslt</书社:id>
  <template match="书社:id[string(.)='example:add-stylesheet-links.xslt']" mode="书社:metadata">
    <html:link rel="stylesheet" type="text/css" href="/style.css"/>
  </template>
</transform>
```

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
  `<书社:archive>`, `<书社:base64-binary>`, or `<书社:raw-text>`
  (described below), or on result trees which do not contain a toplevel
  element in the H·T·M·L namespace.

## 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 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
  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 `书社:` name·space 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 :⁠—

- **`<书社:archive>`:**
  Each child element with a `@书社:archived-as` attribute will be
    archived as a separate file in a resulting tarball (this attribute
    gives the file name).
  These elements will be processed the same as the root elements of any
    other file (e·g, they will be wrapped; they can themselves specify
    non X·M·L output types, ⁊·c).
  Other child elements will be ignored.

  If the `<书社:archive>` element is given an `@书社:expanded`
    attribute, rather than producing a tarball ⛩📰 书社 will output
    the directory which expanding the tarball would produce.
  This mechanism can be used to generate multiple files from a single
    source, provided all of the files are contained with·in the same
    directory.

- **`<书社: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.

- **`<书社:raw-text>`:**
  A plaintext (U·T·F‐8) file will be produced from the text nodes in
    the transformation result.

## License

This repository conforms to [REUSE][].

Most source files are licensed under the terms of the <cite>Mozilla
  Public License, version 2.0</cite>.

[F3C]: <https://darwinsys.com/file/>
[REUSE]: <https://reuse.software/spec/>
[Sharutils]: <https://www.gnu.org/software/sharutils/>
[draft-phillips-record-jar-01]: <https://datatracker.ietf.org/doc/html/draft-phillips-record-jar-01>
[rdar-92753335]: <https://github.com/apple-oss-distributions/patch_cmds/blob/5084833f90df1b0e0924ea56f94c0199b3b8bbc6/diff/diffreg.c#L1800-L1808>
[so-17148468-comment]: <https://stackoverflow.com/questions/17148468/capturing-filenames-including-parentheses-with-gnu-makes-wildcard-function#comment24825307_17148894>