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†.
26 † Assuming an operating system with a fairly featureful, and
27 Posix‐compliant, development setup (e·g, macOS).
28 In fact, on Linux you will probably need to install a few programs:
29 `libxml2-utils`, `xsltproc`, `sharutils`, and `pax`.
33 <i lang="cmn-Hans">书社</i> is a Chinese word meaning “publishing
36 The first character, <i lang="cmn-Hans">书</i>, is the simplified form
39 The second character, <i lang="cmn-Hans">社</i>, contemporarily means
40 “association”, but historically referred to the god of the soil and
41 related altars or festivities.
42 In Japanese, it is an alternate spelling for <i lang="ja">やしろ</i>,
43 the word for “Shinto shrine”.
45 The name <i lang="cmn-Hans">书社</i> was chosen to play on this pun, as
46 it is intended as a publishing program for webshrines.
48 In Ascii environments, ⛩️📰 书社 should be written `Shushe`, following
49 the pinyin transliteration.
53 In most cases, ⛩️📰 书社 aims to require only functionality which is
54 present in all Posix‐compliant operating systems.
55 There are a few exceptions.
56 Details on particular programs are given below; if a program is not
57 listed, it is assumed that any Posix‐compliant implementation will
62 This is a Posix utility, but ⛩️📰 书社 currently depends on
63 unspecified behaviour.
64 When the G·N·U version of `stat` is being used, then the G·N·U version
65 of `date` is also expected.
69 This is a Posix utility, but ⛩️📰 书社 currently depends on
70 unspecified behaviour.
71 It requires support for the following additional options :—
73 - **`-C`**, when supplied with `-m`, must be useable to compile a
74 `.mgc` magicfile for use with future invocations of `file`.
76 - **`--files-from`** must be useable to provide a file that `file`
77 should read file·names from, and `-` must be useable in this
78 context to specify the standard input.
80 - **`--mime-type`** must cause `file` to print the internet media type
81 of the file with no charset parameter.
83 - **`--separator`** must be useable to set the separator that `file`
84 uses to separate file names from types.
86 These options are implemented by the
87 [Fine Free File Command](https://darwinsys.com/file/), which is used
88 by most operating systems.
92 This is not a Posix utility.
93 Usage of `git` is optional, but recommended (and activated by default).
94 To disable it, set `GIT=`.
98 This is a Posix utility, but ⛩️📰 书社 currently depends on
99 unspecified behaviour.
100 ⛩️📰 书社 requires specifically the G·N·U version of `make`, and
101 depends on functionality present in version 3.81 or later.
102 It is not expected to work in previous versions, or with other
103 implementations of Make.
107 This is a Posix utility, but not included in the Linux Standard Base or
108 installed by default in many distributions.
109 Only `ustar` format support is required.
113 This is not a Posix utility, and nor is it particularly portable.
114 To get around incompatibilities, ⛩️📰 书社 attempts to recognize G·N·U
115 `stat` by searching for the string `GNU` when invoked with the
116 `--version` option, and falls back to B·S·D behaviour otherwise.
118 ### `uudecode` and `uuencode`
120 These are Posix utilities, but not included in the Linux Standard Base
121 or installed by default in many distributions.
122 The G·N·U [Sharutils](https://www.gnu.org/software/sharutils/) package
123 can be installed to access them.
125 ### `xmlcatalog` and `xmllint`
127 These are not a Posix utilities.
128 They is a part of `libxml2`, but may need to be installed separately
129 (e·g by the name `libxml2-utils`).
133 This is not a Posix utility.
134 It is a part of `libxslt`, but may need to be installed separately.
138 Place source files in `sources/` and run `make install` to compile
139 the result to `public/`.
140 Compilation involves the following steps :—
142 1. ⛩️📰 书社 compiles all of the magic files in `magic/` into a single
143 file, `build/magic.mgc`.
145 2. ⛩️📰 书社 processes all of the parsers in `parsers/` and determines
146 the list of supported plaintext types.
148 3. ⛩️📰 书社 identifies all of the source files and includes and uses
149 `build/magic.mgc` to classify them by media type.
151 4. ⛩️📰 书社 parses all plaintext and X·M·L source files and includes
152 and then builds a dependency tree between them.
154 5. ⛩️📰 书社 uses the dependency tree to establish prerequisites for
157 6. ⛩️📰 书社 compiles each output file to `build/result`.
159 7. ⛩️📰 书社 copies most output files from `build/result` to
160 `build/public`, but it does some additional processing instead on
161 those which indicate a non‐X·M·L desired final output form.
163 8. ⛩️📰 书社 copies the final resulting files to `public`.
165 You can use `make list` to list each identified source file or include
166 alongside its computed type and dependencies.
167 As this is a Make‐based program, steps will only be run if the
168 corresponding buildfile or output file is older than its
173 The ⛩️📰 书社 name·space is `urn:fdc:ladys.computer:20231231:Shu1She4`.
175 This document uses a few name·space prefixes, with the following
178 | Prefix | Expansion |
179 | ---------: | :-------------------------------------------- |
180 | `catalog:` | `urn:oasis:names:tc:entity:xmlns:xml:catalog` |
181 | `exsl:` | `http://exslt.org/common` |
182 | `exslstr:` | `http://exslt.org/strings` |
183 | `html:` | `http://www.w3.org/1999/xhtml` |
184 | `svg:` | `http://www.w3.org/2000/svg` |
185 | `xlink:` | `http://www.w3.org/1999/xlink` |
186 | `xslt:` | `http://www.w3.org/1999/XSL/Transform` |
187 | `书社:` | `urn:fdc:ladys.computer:20231231:Shu1She4` |
189 ## Setup and Configuration
191 ⛩️📰 书社 depends on the following programs to run.
192 In every case, you may supply your own implementation by overriding the
193 corresponding (allcaps) variable (e·g, set `MKDIR` to supply your own
194 `mkdir` implementation).
203 - `git` (optional; set `GIT=` to disable)
210 - `pax` (only when generating archives)
215 - `stat` (BSD *or* GNU)
222 - `xmlcatalog` (provided by `libxml2`)
223 - `xmllint` (provided by `libxml2`)
224 - `xsltproc` (provided by `libxslt`)
226 The following additional variables can be used to control the behaviour
230 The location of the source files (default: `sources`).
231 Multiple source directories can be provided, so long as the same
232 file subpath doesn’t exist in more than one of them.
235 The location of source includes (default: `sources/includes`).
236 This can be inside of `SRCDIR`, but needn’t be.
237 Multiple include directories can be provided, so long as the same
238 file subpath doesn’t exist in more than one of them.
241 The location of the (temporary) build directory (default: `build`).
242 `make clean` will delete this, and it is recommended that it not be
243 used for programs aside from ⛩️📰 书社.
246 The location of directory to output files to (default: `public`).
247 `make install` will overwrite files in this directory which
248 correspond to those in `SRCDIR`.
249 It *will not* touch other files, including those generated from files
250 in `SRCDIR` which have since been deleted.
252 Files are first compiled to `$(BUILDDIR)/public` before they are
253 copied to `DESTDIR`, so this folder is relatively quick and
254 inexpensive to re·create.
255 It’s reasonable to simply delete it before every `make install` to
256 ensure stale content is removed.
259 The location of the ⛩️📰 书社 `GNUmakefile`.
260 This should be set automatically when calling Make and shouldn’t ever
261 need to be set manually.
262 This variable is used to find the ⛩️📰 书社 `lib/` folder, which is
263 expected to be in the same location.
266 A white·space‐separated list of magic files to use (default:
267 `$(THISDIR)/magic/*`).
270 The value of this variable is appended to `MAGIC` by default, to
271 enable additional magic files without overriding the existing ones.
274 Rules to use with `find` when searching for source files.
275 The default ignores files that start with a period or hyphen‐minus,
276 those which end with a cloparen, and those which contain a hash,
277 buck, percent, asterisk, colon, semi, eroteme, bracket, backslash,
280 - **`EXTRAFINDRULES`:**
281 The value of this variable is appended to `FINDRULES` by default, to
282 enable additional rules without overriding the existing ones.
284 - **`FINDINCLUDERULES`:**
285 Rules to use with `find` when searching for includes (default:
288 - **`EXTRAFINDINCLUDERULES`:**
289 The value of this variable is appended to `FINDINCLUDERULES` by
290 default, to enable additional rules without overriding the existing
294 A white·space‐separated list of parsers to use (default:
295 `$(THISDIR)/parsers/*.xslt`).
297 - **`EXTRAPARSERS`:**
298 The value of this variable is appended to `PARSERS` by default, to
299 enable additional parsers without overriding the existing ones.
302 A white·space‐separated list of transforms to use (default:
303 `$(THISDIR)/transforms/*.xslt`).
305 - **`EXTRATRANSFORMS`:**
306 The value of this variable is appended to `TRANSFORMS` by default, to
307 enable additional transforms without overriding the existing ones.
310 A white·space‐separated list of media types to consider X·M·L
311 (default: `application/xml text/xml`).
314 The current version of ⛩️📰 书社 (default: derived from the current
315 git tag/branch/commit).
318 The current version of the source files (default: derived from the
319 current git tag/branch/commit).
322 If this variable has a value, every recipe instruction will be
323 printed when it runs (default: empty).
324 This is helpful for debugging, but typically too noisy for general
329 Source files may be placed in `SRCDIR` in any manner; the file
330 structure used there will match the output.
331 The type of source files is *not* determined by file extension, but
332 rather by magic number; this means that files **must** begin with
333 something recognizable.
334 Supported magic numbers include :—
336 - `<?xml` for `application/xml` files
337 - `#!js` for `text/javascript` files
338 - `@charset "` for `text/css` files
339 - `#!tsv` for `text/tab-separated-values` files
340 - `%%` for `text/record-jar` files (unregistered; see
341 [[draft-phillips-record-jar-01][]])
343 Text formats with associated X·S·L·T parsers are wrapped in a H·T·M·L
344 `<script>` element whose `@type` gives its media type, and then
345 passed to the parser to process.
346 Source files whose media type does not have an associated X·S·L·T
347 parser are considered “assets” and will not be transformed.
349 **☡ For compatibility with this program, source file·names must not
350 contain Ascii white·space, colons (`:`), semis (`;`), pipes (`|`),
351 bucks (`$`), percents (`%`), hashes (`#`), asterisks (`*`), brackets
352 (`[` or `]`), erotemes (`?`), backslashes (`\`), or control
353 characters, must not begin with a hyphen‐minus (`-`), must not end
354 with a cloparen (`)`), and must not contain quoted braces (`"{` or
356 The former characters have the potential to conflict with make syntax,
357 a leading hyphen‐minus is confusable for a command‐line argument, a
358 trailing cloparen [activates a bug in G·N·U Make
359 3.81](https://stackoverflow.com/questions/17148468/capturing-filenames-including-parentheses-with-gnu-makes-wildcard-function#comment24825307_17148894),
360 and quoted braces are used internally by the program.
364 Parsers are used to convert plaintext files into X·M·L trees, as well
365 as convert plaintext formats which are already included inline in
366 existing source X·M·L documents.
367 ⛩️📰 书社 comes with some parsers; namely :—
369 - **`parsers/plain.xslt`:**
370 Wraps `text/plain` contents in a `<html:pre>` element.
372 - **`parsers/record-jar.xslt`:**
373 Converts `text/record-jar` contents into a `<html:div>` of
374 `<html:dl>` elements (one for each record).
376 - **`parsers/tsv.xslt`:**
377 Converts `text/tab-separated-values` contents into an `<html:table>`
380 New ⛩️📰 书社 parsers which target plaintext formats should have an
381 `<xslt:template>` element with no `@name` or `@mode` and whose
384 - Starts with an appropriately‐name·spaced qualified name for a
385 `<html:script>` element.
387 - Follows this with the string `[@type=`.
389 - Follows this with a quoted string giving a media type supported by
391 Media type parameters are *not* supported.
393 - Follows this with the string `]`.
395 For example, the trivial `text/plain` parser is defined as follows :—
398 <?xml version="1.0"?>
400 xmlns="http://www.w3.org/1999/XSL/Transform"
401 xmlns:html="http://www.w3.org/1999/xhtml"
402 xmlns:书社="urn:fdc:ladys.computer:20231231:Shu1She4"
405 <书社:id>example:text/plain</书社:id>
406 <template match="html:script[@type='text/plain']">
407 <html:pre><value-of select="."/></html:pre>
412 ⛩️📰 书社 will scan the provided parsers for this pattern to determine
413 the set of allowed plaintext file types.
414 Multiple such `<xslt:template>` elements may be provided in a single
415 parser, for example if the parser supports multiple media types.
416 Alternatively, you can set the `@书社:supported-media-types` attribute
417 on the root element of the parser to override media type support
420 Even when `@书社:supported-media-types` is set, it is a requirement
421 that each parser transform any `<html:script>` elements with a
422 `@type` which matches their registered types into something else.
423 Otherwise the parser will be stuck in an endless loop.
424 The result tree of applying the transform to the `<html:script>`
425 element will be reparsed (in case any new `<html:script>` elements
426 were added in its subtree), and a `@书社:parsed-by` attribute will be
427 added to each toplevel element in the result.
428 The value of this attribute will be the value of the `<书社:id>`
429 toplevel element in the parser.
431 It is possible for parsers to support zero plaintext types.
432 This is useful when targeting specific dialects of X·M·L; parsers in
433 this sense operate on the same basic principles as transforms
435 The major distinction between X·M·L parsers and transforms is where in
436 the process the transformation happens:
437 Parsers are applied *prior* to embedding (and can be used to generate
438 embeds); transforms are applied *after*.
440 It is **strongly recommended** that auxillary templates in parsers be
441 name·spaced (by `@name` or `@mode`) whenever possible, to avoid
442 conflicts between parsers.
444 ### Attributes added during parsing
446 ⛩️📰 书社 will add a few attributes to the output of the parsing step,
449 - A `@书社:cksum` attribute on toplevel result elements, giving the
450 `cksum` checksum of the corresponding source file.
452 - For the elements which result from parsing plaintext `<html:script>`
455 - A `@书社:parsed-by` attribute, giving a space‐separated list of
456 parsers which parsed the node.
457 (Generally, this will be a list of one, but it is possible for the
458 result of a parse to be another plaintext node, which may be
459 parsed by a different parser.)
461 - A `@书社:media-type` attribute, giving the identified media type of
466 Documents can be embedded in other documents using a `<书社:link>`
467 element with `@xlink:show="embed"`.
468 The `@xlink:href`s of these elements should have the format
469 `about:shushe?source=<path>`, where `<path>` provides the path to the
470 file within `SRCDIR`.
471 Includes, which do not generate outputs of their own but may still be
472 freely embedded, instead use the format
473 `about:shushe?include=<path>`, where `<path>` provides the path
476 Embeds are replaced with the parsed contents of a file, unless the file
477 is an asset, in which case an `<html:object>` element is produced
478 instead (with the contents of the asset file provided as a base64
480 Embed replacements will be given a `@书社:identifier` attribute whose
481 value will match the `@xlink:href` of the embed.
483 Embedding takes place after parsing but before transformation, so
484 parsers are able to generate their own embeds.
485 ⛩️📰 书社 is able to detect the transitive embed dependencies of files
486 and update them accordingly; it will signal an error if the
487 dependencies are recursive.
489 ## Output Redirection
491 By default, ⛩️📰 书社 installs files to the same location in `DESTDIR`
492 as they were placed in their `SRCDIR`.
493 This behaviour can be customized by setting the `@书社:destination`
494 attribute on the root element, whose value can give a different path.
495 This attribute is read after parsing, but before transformation (where
496 it is silently dropped).
500 Transforms are used to convert X·M·L files into their final output,
501 after all necessary parsing and embedding has taken place.
502 ⛩️📰 书社 comes with some transforms; namely :—
504 - **`transforms/asset.xslt`:**
505 Converts `<html:object>` elements which correspond to recognized
506 media types into the appropriate H·T·M·L elements, and deletes
507 `<html:style>` elements from the body of the document and moves
510 - **`transforms/metadata.xslt`:**
511 Provides basic `<html:head>` metadata.
512 This metadata is generated from `<html:meta>` elements with one of
513 the following `@itemprop` attributes :—
515 - **`urn:fdc:ladys.computer:20231231:Shu1She4:title`:**
516 Provides the title of the page.
518 ⛩️📰 书社 automatically encapsulates H·T·M·L embeds so that their
519 metadata does not propogate up to the embedding document.
520 To undo this behaviour, remove the `@itemscope` and `@itemtype`
521 attributes from the embed during the transformation phase.
523 - **`transforms/serialization.xslt`:**
524 Replaces `<书社:serialize-xml>` elements with the (escaped)
525 serialized X·M·L of their contents.
526 This replacement happens during the application phase, after most
527 other transformations have taken place.
529 If a `@with-namespaces` attribute is provided, any name·space nodes
530 on the toplevel serialized elements whose U·R·I’s correspond to the
531 definitions of the provided prefixes, as defined for the
532 `<书社:serialize-xml>` element, will be declared using name·space
533 attributes on the serialized elements.
534 Otherwise, only name·space nodes which _differ_ from the definitions
535 on the `<书社:serialize-xml>` element will be declared.
536 The string `#default` may be used to represent the default
538 Multiple prefixes may be provided, separated by white·space.
540 When it comes to name·spaces used internally by ⛩️📰 书社, the
541 prefix used by ⛩️📰 书社 may be declared _in addition to_ the
542 prefix(es) used in the source document(s).
543 It is not possible to selectively only declare one prefix for a
544 name·space to the exclusion of others.
546 `<书社:raw-output>` elements may be used inside of
547 `<书社:serialize-xml>` elements to inject raw output into the
550 The following are recommendations on effective creation of
553 - Make template matchers as specific as possible.
554 It is likely an error if two transforms have templates which match
555 the same element (unless the templates have different priority).
557 - Name·space templates (with `@name` or `@mode`) whenever possible.
559 - Set `@exclude-result-prefixes` on the root `xslt:transform` element
560 to reduce the number of declared name·spaces in the final result.
564 The following params are made available globally in parsers and
571 The checksum of the source file (⅌ `cksum`).
574 The ⛩️📰 书社 identifier of the source file (a u·r·i beginning with
578 The value of the `SRCREV` variable (if present).
581 The time at which the source file was last modified.
584 The value of the `THISREV` variable (if present).
586 The following params are only available in transforms :—
589 The path of the catalog file (within `BUILDDIR`).
592 The path of the output file (within `DESTDIR`).
596 ⛩️📰 书社 will wrap the final output of the transforms in appropriate
597 `<html:html>` and `<html:body>` elements, so it is not necessary for
598 transforms to do this explicitly.
599 After performing the initial transform, ⛩️📰 书社 will match the root
600 node of the result in the following modes to fill in areas of the
604 The result of matching in this mode is prepended into the
605 `<html:body>` of the output (before the transformation result).
608 The result of matching in this mode is appended into the
609 `<html:body>` of the output (after the transformation result).
612 The result of matching in this mode is inserted into the
613 `<html:head>` of the output.
615 In addition to being called with the transform result, each of these
616 modes will additionally be called with a `<xslt:include>` element
617 corresponding to each transform.
618 If a transform has a `<书社:id>` top‐level element whose value is an
619 i·r·i, its `<xslt:include>` element will have a corresponding
621 This mechanism can be used to allow transforms to insert content
622 without matching any elements in the result; for example, the
623 following transform adds a link to a stylesheet to the `<html:head>`
627 <?xml version="1.0"?>
629 xmlns="http://www.w3.org/1999/XSL/Transform"
630 xmlns:html="http://www.w3.org/1999/xhtml"
631 xmlns:xslt="http://www.w3.org/1999/XSL/Transform"
632 xmlns:书社="urn:fdc:ladys.computer:20231231:Shu1She4"
633 exclude-result-prefixes="书社"
636 <书社:id>example:add-stylesheet-links.xslt</书社:id>
637 <template match="xslt:include[@书社:id='example:add-stylesheet-links.xslt']" mode="书社:metadata">
638 <html:link rel="stylesheet" type="text/css" href="/style.css"/>
643 Output wrapping can be entirely disabled by adding a
644 `@书社:disable-output-wrapping` attribute to the top‐level element in
646 It will not be performed on outputs whose root elements are
647 `<书社:archive>`, `<书社:base64-binary>`, or `<书社:raw-text>`
650 ## Applying Attributes
652 The `<书社:apply-attributes>` element will apply any attributes on the
653 element to the element(s) it wraps.
654 It is especially useful in combination with embeds.
656 The `<书社:apply-attributes-to-root>` element will apply any attributes
657 on the element to the root node of the final transformation result.
658 It is especially useful in combination with output wrapping.
660 In both cases, attributes from various sources are combined with
661 white·space between them.
662 Attribute application takes place after all ordinary transforms have
665 Both elements ignore attributes in the `xml:` name·space, except for
666 `@xml:lang`, which ignores all but the first definition (including
667 any already present on the root element).
668 On H·T·M·L and S·V·G elements, `@lang` has the same behaviour as
671 ## Other Kinds of Output
673 There are a few special elements in the `书社:` name·space which, if
674 they appear as the toplevel element in a transformation result, cause
675 ⛩️📰 书社 to produce something other than an X·M·L file.
678 - **`<书社:archive>`:**
679 Each child element with a `@书社:archived-as` attribute will be
680 archived as a separate file in a resulting tarball (this attribute
681 gives the file name).
682 These elements will be processed the same as the root elements of any
683 other file (e·g, they will be wrapped; they can themselves specify
684 non X·M·L output types, ⁊·c).
685 Other child elements will be ignored.
687 If the `<书社:archive>` element is given an `@书社:expanded`
688 attribute, rather than producing a tarball ⛩️📰 书社 will output
689 the directory which expanding the tarball would produce.
690 This mechanism can be used to generate multiple files from a single
691 source, provided all of the files are contained with·in the same
694 - **`<书社:base64-binary>`:**
695 The text nodes in the transformation result will, after removing all
696 Ascii whitespace, be treated as a Base·64 string, which is then
699 - **`<书社:raw-text>`:**
700 A plaintext (U·T·F‐8) file will be produced from the text nodes in
701 the transformation result.
705 It is possible to have a single source file produce multiple output
706 files via `<书社:page>` elements, whose `@name` gives the name of the
708 If a parsed document has a `@书社:destination` which contains `%s`,
709 the `%s` will be replaced with the `@name` for each `<书社:page>` (and
710 removed for the main output).
711 Otherwise, the `@name` is inserted before the first period of the
712 filename (or at the end of the filename for those with no period).
713 If `<书社:page>`s do not have a `@name`, they are numbered
715 The destination of pages must be in the same directory as their parent.
717 Pagination essentially forms a limited convenience for the more
718 sophisticated technique of creating an archive with ⛩️📰 书社 and
720 Pages are, from Make’s point of view, untracked side·effects of
721 installing the main output, meaning they cannot be targeted directly
722 and will not appear in `make list` or `make listout`.
723 They are intended solely for the like of indices and feeds, for which
724 convenience and necessity outweigh their flaws.
728 This repository conforms to [REUSE][].
730 Most source files are licensed under the terms of the <cite>Mozilla
731 Public License, version 2.0</cite>.
733 [REUSE]: <https://reuse.software/spec/>
734 [draft-phillips-record-jar-01]: <https://datatracker.ietf.org/doc/html/draft-phillips-record-jar-01>