2 SPDX-FileCopyrightText: 2024 Lady <https://www.ladys.computer/about/#lady>
3 SPDX-License-Identifier: CC0-1.0
7 <b>A make·file for X·M·L.</b>
9 <dfn>⛩️📰 书社</dfn> aims to make it easy to generate websites with
10 X·S·L·T and G·N·U Make.
11 It is consequently only a good choice for people who like X·S·L·T and
12 G·N·U Make and wish it were easier to make websites with them.
14 It makes things easier by :—
16 - Automatically identifying source files and characterizing them by
17 type (X·M·L, text, or asset).
19 - Parsing supported text types into X·M·L trees.
21 - Enabling easy inclusion of source files within each other.
23 It aims to do this with zero dependencies beyond the programs already
24 installed on your computer.
25 (On Linux machines, you may need to install `libxml2-utils` to get the
26 commandline programs from `libxml2`.)
29 ⛩️📰 书社 requires functionality present in G·N·U Make 3.81 (or later)
30 and will not work in previous versions, or other implementations of
32 Compatibility with later versions of G·N·U Make is assumed, but not
37 <i lang="cmn-Hans">书社</i> is a Chinese word meaning “publishing
40 The first character, <i lang="cmn-Hans">书</i>, is the simplified form
43 The second character, <i lang="cmn-Hans">社</i>, contemporarily means
44 “association”, but historically referred to the god of the soil and
45 related altars or festivities.
46 In Japanese, it is an alternate spelling for <i lang="ja">やしろ</i>,
47 the word for “Shinto shrine”.
49 The name <i lang="cmn-Hans">书社</i> was chosen to play on this pun, as
50 it is intended as a publishing program for webshrines.
52 In Ascii environments, ⛩️📰 书社 should be written `Shushe`, following
53 the pinyin transliteration.
57 Place source files in `sources/` and run `make install` to compile
58 the result to `public/`.
59 Compilation involves the following steps :—
61 1. ⛩️📰 书社 compiles all of the magic files in `magic/` into a single
62 file, `build/magic.mgc`.
64 2. ⛩️📰 书社 processes all of the parsers in `parsers/` and determines
65 the list of supported plaintext types.
67 3. ⛩️📰 书社 identifies all of the source files and includes and uses
68 `build/magic.mgc` to classify them by media type.
70 4. ⛩️📰 书社 parses all plaintext and X·M·L source files and includes
71 and then builds a dependency tree between them.
73 5. ⛩️📰 书社 uses the dependency tree to establish prerequisites for
76 6. ⛩️📰 书社 compiles each output file to `build/result`.
78 7. ⛩️📰 书社 symlinks most output files from `build/result` to
79 `build/public`, but it does some additional processing instead on
80 those which indicate a non‐X·M·L desired final output form.
82 8. ⛩️📰 书社 copies the final resulting files to `public`.
84 You can use `make list` to list each identified source file or include
85 alongside its computed type and dependencies.
86 As this is a Make‐based program, steps will only be run if the
87 corresponding buildfile or output file is older than its
92 The ⛩️📰 书社 namespace is `urn:fdc:ladys.computer:20231231:Shu1She4`.
94 This document uses a few namespace prefixes, with the following
97 | Prefix | Expansion |
98 | -------: | :----------------------------------------- |
99 | `html:` | `http://www.w3.org/1999/xhtml` |
100 | `xlink:` | `http://www.w3.org/1999/xlink` |
101 | `xslt:` | `http://www.w3.org/1999/XSL/Transform` |
102 | `书社:` | `urn:fdc:ladys.computer:20231231:Shu1She4` |
104 ## Setup and Configuration
106 ⛩️📰 书社 depends on the following programs to run.
107 In every case, you may supply your own implementation by overriding the
108 corresponding (allcaps) variable (e·g, set `MKDIR` to supply your own
109 `mkdir` implementation).
119 - `git` (optional; set `GIT=` to disable)
121 - `mkdir` (requires support for `-p`)
123 - `od` (requires support for `-t x1`)
124 - `pax` (only when generating archives)
132 - `tr` (requires support for `-d`)
133 - `uuencode` (requires support for `-m` and `-r`)
134 - `uudecode` (requires support for `-m` and `-r`)
135 - `xargs` (requires support for `-0`)
136 - `xmlcatalog` (provided by `libxml2`)
137 - `xmllint` (provided by `libxml2`)
138 - `xsltproc` (provided by `libxslt`)
140 The following additional variables can be used to control the behaviour
144 The location of the source files (default: `sources`).
145 Multiple source directories can be provided, so long as the same
146 file subpath doesn’t exist in more than one of them.
149 The location of source includes (default: `sources/includes`).
150 This can be inside of `SRCDIR`, but needn’t be.
151 Multiple include directories can be provided, so long as the same
152 file subpath doesn’t exist in more than one of them.
155 The location of the (temporary) build directory (default: `build`).
156 `make clean` will delete this, and it is recommended that it not be
157 used for programs aside from ⛩️📰 书社.
160 The location of directory to output files to (default: `public`).
161 `make install` will overwrite files in this directory which
162 correspond to those in `SRCDIR`.
163 It *will not* touch other files, including those generated from files
164 in `SRCDIR` which have since been deleted.
166 Files are first compiled to `$(BUILDDIR)/public` before they are
167 copied to `DESTDIR`, so this folder is relatively quick and
168 inexpensive to re·create.
169 It’s reasonable to simply delete it before every `make install` to
170 ensure stale content is removed.
173 The location of the ⛩️📰 书社 `GNUmakefile`.
174 This should be set automatically when calling Make and shouldn’t ever
175 need to be set manually.
176 This variable is used to find the ⛩️📰 书社 `lib/` folder, which is
177 expected to be in the same location.
180 A white·space‐separated list of magic files to use (default:
181 `$(THISDIR)/magic/*`).
184 The value of this variable is appended to `MAGIC` by default, to
185 enable additional magic files without overriding the existing ones.
188 Rules to use with `find` when searching for source files.
189 The default ignores files that start with a period or hyphen‐minus,
190 those which end with a cloparen, and those which contain a hash,
191 buck, percent, asterisk, colon, semi, eroteme, bracket, backslash,
194 - **`EXTRAFINDRULES`:**
195 The value of this variable is appended to `FINDRULES` by default, to
196 enable additional rules without overriding the existing ones.
198 - **`FINDINCLUDERULES`:**
199 Rules to use with `find` when searching for includes (default:
202 - **`EXTRAFINDINCLUDERULES`:**
203 The value of this variable is appended to `FINDINCLUDERULES` by
204 default, to enable additional rules without overriding the existing
208 A white·space‐separated list of parsers to use (default:
209 `$(THISDIR)/parsers/*.xslt`).
211 - **`EXTRAPARSERS`:**
212 The value of this variable is appended to `PARSERS` by default, to
213 enable additional parsers without overriding the existing ones.
216 A white·space‐separated list of transforms to use (default:
217 `$(THISDIR)/transforms/*.xslt`).
219 - **`EXTRATRANSFORMS`:**
220 The value of this variable is appended to `TRANSFORMS` by default, to
221 enable additional transforms without overriding the existing ones.
224 A white·space‐separated list of media types to consider X·M·L
225 (default: `application/xml text/xml`).
228 The current version of ⛩️📰 书社 (default: derived from the current
229 git tag/branch/commit).
232 The current version of the source files (default: derived from the
233 current git tag/branch/commit).
236 If this variable has a value, every recipe instruction will be
237 printed when it runs (default: empty).
238 This is helpful for debugging, but typically too noisy for general
243 Source files may be placed in `SRCDIR` in any manner; the file
244 structure used there will match the output.
245 The type of source files is *not* determined by file extension, but
246 rather by magic number; this means that files **must** begin with
247 something recognizable.
248 Supported magic numbers include :—
250 - `<?xml` for `application/xml` files
251 - `#!js` for `text/javascript` files
252 - `@charset "` for `text/css` files
253 - `#!tsv` for `text/tab-separated-values` files
254 - `%%` for `text/record-jar` files (unregistered; see
255 [[draft-phillips-record-jar-01][]])
257 Text formats with associated X·S·L·T parsers are wrapped in a H·T·M·L
258 `<script>` element whose `@type` gives its media type, and then
259 passed to the parser to process.
260 Source files whose media type does not have an associated X·S·L·T
261 parser are considered “assets” and will not be transformed.
263 **☡ For compatibility with this program, source file·names must not
264 contain Ascii white·space, colons (`:`), semis (`;`), pipes (`|`),
265 bucks (`$`), percents (`%`), hashes (`#`), asterisks (`*`), brackets
266 (`[` or `]`), erotemes (`?`), backslashes (`\`), or control
267 characters, must not begin with a hyphen‐minus (`-`), and must not
268 end with a cloparen (`)`).**
269 The former characters have the potential to conflict with make syntax,
270 a leading hyphen‐minus is confusable for a command‐line argument, and
271 a trailing cloparen [activates a bug in G·N·U Make
272 3.81](https://stackoverflow.com/questions/17148468/capturing-filenames-including-parentheses-with-gnu-makes-wildcard-function#comment24825307_17148894).
276 Parsers are used to convert plaintext files into X·M·L trees, as well
277 as convert plaintext formats which are already included inline in
278 existing source X·M·L documents.
279 ⛩️📰 书社 comes with some parsers; namely :—
281 - **`parsers/plain.xslt`:**
282 Wraps `text/plain` contents in a `<html:pre>` element.
284 - **`parsers/record-jar.xslt`:**
285 Converts `text/record-jar` contents into a `<html:div>` of
286 `<html:dl>` elements (one for each record).
288 - **`parsers/tsv.xslt`:**
289 Converts `text/tab-separated-values` contents into an `<html:table>`
292 New ⛩️📰 书社 parsers which target plaintext formats should have an
293 `<xslt:template>` element with no `@name` or `@mode` and whose
296 - Starts with an appropriately‐namespaced qualified name for a
297 `<html:script>` element.
299 - Follows this with the string `[@type=`.
301 - Follows this with a quoted string giving a media type supported by
303 Media type parameters are *not* supported.
305 - Follows this with the string `]`.
307 For example, the trivial `text/plain` parser is defined as follows :—
310 <?xml version="1.0"?>
312 xmlns="http://www.w3.org/1999/XSL/Transform"
313 xmlns:html="http://www.w3.org/1999/xhtml"
314 xmlns:书社="urn:fdc:ladys.computer:20231231:Shu1She4"
317 <书社:id>example:text/plain</书社:id>
318 <template match="html:script[@type='text/plain']">
319 <html:pre><value-of select="."/></html:pre>
324 ⛩️📰 书社 will scan the provided parsers for this pattern to determine
325 the set of allowed plaintext file types.
326 Multiple such `<xslt:template>` elements may be provided in a single
327 parser, for example if the parser supports multiple media types.
328 Alternatively, you can set the `@书社:supported-media-types` attribute
329 on the root element of the parser to override media type support
332 Even when `@书社:supported-media-types` is set, it is a requirement
333 that each parser transform any `<html:script>` elements with a
334 `@type` which matches their registered types into something else.
335 Otherwise the parser will be stuck in an endless loop.
336 The result tree of applying the transform to the `<html:script>`
337 element will be reparsed (in case any new `<html:script>` elements
338 were added in its subtree), and a `@书社:parsed-by` attribute will be
339 added to each toplevel element in the result.
340 The value of this attribute will be the value of the `<书社:id>`
341 toplevel element in the parser.
343 It is possible for parsers to support zero plaintext types.
344 This is useful when targeting specific dialects of X·M·L; parsers in
345 this sense operate on the same basic principles as transforms
347 The major distinction between X·M·L parsers and transforms is where in
348 the process the transformation happens:
349 Parsers are applied *prior* to embedding (and can be used to generate
350 embeds); transforms are applied *after*.
352 It is **strongly recommended** that auxillary templates in parsers be
353 namespaced (by `@name` or `@mode`) whenever possible, to avoid
354 conflicts between parsers.
356 ### Attributes added during parsing
358 ⛩️📰 书社 will add a few attributes to the output of the parsing step,
361 - A `@书社:cksum` attribute on toplevel result elements, giving the
362 `cksum` checksum of the corresponding source file.
364 - For the elements which result from parsing plaintext `<html:script>`
367 - A `@书社:parsed-by` attribute, giving a space‐separated list of
368 parsers which parsed the node.
369 (Generally, this will be a list of one, but it is possible for the
370 result of a parse to be another plaintext node, which may be
371 parsed by a different parser.)
373 - A `@书社:media-type` attribute, giving the identified media type of
378 Documents can be embedded in other documents using a `<书社:link>`
379 element with `@xlink:show="embed"`.
380 The `@xlink:href`s of these elements should have the format
381 `about:shushe?source=<path>`, where `<path>` provides the path to the
382 file within `SRCDIR`.
383 Includes, which do not generate outputs of their own but may still be
384 freely embedded, instead use the format
385 `about:shushe?include=<path>`, where `<path>` provides the path
388 Embeds are replaced with the parsed contents of a file, unless the file
389 is an asset, in which case an `<html:object>` element is produced
390 instead (with the contents of the asset file provided as a base64
392 Embed replacements will be given a `@书社:identifier` attribute whose
393 value will match the `@xlink:href` of the embed.
395 Embedding takes place after parsing but before transformation, so
396 parsers are able to generate their own embeds.
397 ⛩️📰 书社 is able to detect the transitive embed dependencies of files
398 and update them accordingly; it will signal an error if the
399 dependencies are recursive.
401 ## Output Redirection
403 By default, ⛩️📰 书社 installs files to the same location in `DESTDIR`
404 as they were placed in their `SRCDIR`.
405 This behaviour can be customized by setting the `@书社:destination`
406 attribute on the root element, whose value can give a different path.
407 This attribute is read after parsing, but before transformation (where
408 it is silently dropped).
412 Transforms are used to convert X·M·L files into their final output,
413 after all necessary parsing and embedding has taken place.
414 ⛩️📰 书社 comes with some transforms; namely :—
416 - **`transforms/asset.xslt`:**
417 Converts `<html:object>` elements which correspond to recognized
418 media types into the appropriate H·T·M·L elements, and deletes
419 `<html:style>` elements from the body of the document and moves
422 - **`transforms/metadata.xslt`:**
423 Provides basic `<html:head>` metadata.
424 This metadata is generated from `<html:meta>` elements with one of
425 the following `@itemprop` attributes :—
427 - **`urn:fdc:ladys.computer:20231231:Shu1She4:title`:**
428 Provides the title of the page.
430 ⛩️📰 书社 automatically encapsulates H·T·M·L embeds so that their
431 metadata does not propogate up to the embedding document.
432 To undo this behaviour, remove the `@itemscope` and `@itemtype`
433 attributes from the embed during the transformation phase.
435 The following are recommendations on effective creation of
438 - Make template matchers as specific as possible.
439 It is likely an error if two transforms have templates which match
440 the same element (unless the templates have different priority).
442 - Namespace templates (with `@name` or `@mode`) whenever possible.
444 - Set `@exclude-result-prefixes` on the root `xslt:transform` element
445 to reduce the number of declared namespaces in the final result.
449 The following params are made available globally in parsers and
456 The checksum of the source file (⅌ `cksum`).
459 The ⛩️📰 书社 identifier of the source file (a u·r·i beginning with
463 The value of the `SRCREV` variable (if present).
466 The time at which the source file was last modified.
469 The value of the `THISREV` variable (if present).
471 The following params are only available in transforms :—
474 The path of the catalog file (within `BUILDDIR`).
477 The path of the output file (within `DESTDIR`).
481 ⛩️📰 书社 will wrap the final output of the transforms in appropriate
482 `<html:html>` and `<html:body>` elements, so it is not necessary for
483 transforms to do this explicitly.
484 After performing the initial transform, ⛩️📰 书社 will match the root
485 node of the result in the following modes to fill in areas of the
489 The result of matching in this mode is prepended into the
490 `<html:body>` of the output (before the transformation result).
493 The result of matching in this mode is appended into the
494 `<html:body>` of the output (after the transformation result).
497 The result of matching in this mode is inserted into the
498 `<html:head>` of the output.
500 In addition to being called with the transform result, each of these
501 modes will additionally be called with a `<xslt:include>` element
502 corresponding to each transform.
503 If a transform has a `<书社:id>` top‐level element whose value is an
504 i·r·i, its `<xslt:include>` element will have a corresponding
506 This mechanism can be used to allow transforms to insert content
507 without matching any elements in the result; for example, the
508 following transform adds a link to a stylesheet to the `<html:head>`
512 <?xml version="1.0"?>
514 xmlns="http://www.w3.org/1999/XSL/Transform"
515 xmlns:html="http://www.w3.org/1999/xhtml"
516 xmlns:xslt="http://www.w3.org/1999/XSL/Transform"
517 xmlns:书社="urn:fdc:ladys.computer:20231231:Shu1She4"
518 exclude-result-prefixes="书社"
521 <书社:id>example:add-stylesheet-links.xslt</书社:id>
522 <template match="xslt:include[@书社:id='example:add-stylesheet-links.xslt']" mode="书社:metadata">
523 <html:link rel="stylesheet" type="text/css" href="/style.css"/>
528 Output wrapping can be entirely disabled by adding a
529 `@书社:disable-output-wrapping` attribute to the top‐level element in
531 It will not be performed on outputs whose root elements are
532 `<书社:archive>`, `<书社:base64-binary>`, or `<书社:raw-text>`
535 ## Applying Attributes
537 The `<书社:apply-attributes>` element will apply any attributes on the
538 element to the element(s) it wraps.
539 It is especially useful in combination with embeds.
541 The `<书社:apply-attributes-to-root>` element will apply any attributes
542 on the element to the root node of the final transformation result.
543 It is especially useful in combination with output wrapping.
545 In both cases, attributes from various sources are combined with
546 white·space between them.
547 Attribute application takes place after all ordinary transforms have
550 Both elements ignore attributes in the `xml:` namespace, except for
551 `@xml:lang`, which ignores all but the first definition (including
552 any already present on the root element).
553 On H·T·M·L and S·V·G elements, `@lang` has the same behaviour as
556 ## Other Kinds of Output
558 There are a few special elements in the `书社:` namespace which, if
559 they appear as the toplevel element in a transformation result, cause
560 ⛩️📰 书社 to produce something other than an X·M·L file.
563 - **`<书社:archive>`:**
564 Each child element with a `@书社:archived-as` attribute will be
565 archived as a separate file in a resulting tarball (this attribute
566 gives the file name).
567 These elements will be processed the same as the root elements of any
568 other file (e·g, they will be wrapped; they can themselves specify
569 non X·M·L output types, ⁊·c).
570 Other child elements will be ignored.
572 - **`<书社:base64-binary>`:**
573 The text nodes in the transformation result will, after removing all
574 Ascii whitespace, be treated as a Base·64 string, which is then
577 - **`<书社:raw-text>`:**
578 A plaintext (U·T·F‐8) file will be produced from the text nodes in
579 the transformation result.
583 This repository conforms to [REUSE][].
585 Most source files are licensed under the terms of the <cite>Mozilla
586 Public License, version 2.0</cite>.
588 [REUSE]: <https://reuse.software/spec/>
589 [draft-phillips-record-jar-01]: <https://datatracker.ietf.org/doc/html/draft-phillips-record-jar-01>