corresponding (allcaps) variable (e·g, set `MKDIR` to supply your own
`mkdir` implementation).
+- `awk`
- `cat`
- `cp`
+- `date`
- `echo`
- `file`
- `find`
- `mkdir` (requires support for `-p`)
- `mv`
+- `od` (requires support for `-t x1`)
- `printf`
- `rm`
- `sed`
- `sleep`
+- `stat`
- `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`)
- **`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 the source files (default: `sources/includes`).
+ 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.
- **`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.
- **`THISDIR`:**
The location of the ⛩️📰 书社 `GNUmakefile`.
- **`MAGICDIR`:**
The location of the magic files to use (default: `$(THISDIR)/magic`).
-- **`FINDOPTS`:**
- Options to pass to `find` when searching for source files (default:
- `-LE`).
-
- **`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 hidden files, those that start with a period or
+ hyphen‐minus, and those which contain a pipe, buck, or colon.
+
+- **`FINDINCLUDERULES`:**
+ Rules to use with `find` when searching for includes (default:
+ `$(FINDRULES)`).
- **`PARSERS`:**
A white·space‐separated list of parsers to use (default:
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 filenames must not
+ contain Ascii whitespace, colons (`:`), pipes (`|`), bucks (`$`),
+ percents (`%`) 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.
## Parsers
⛩️📰 书社 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`:**
- 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.
on the root element of the parser to override media type support
detection.
-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.
+Parsers can also target specific dialects of X·M·L, in which case they
+ 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
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/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/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`:**
- 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).
+
## Output Wrapping
⛩️📰 书社 will wrap the final output of the transforms in appropriate
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
Lady’s Gitweb / Shushe / blobdiff