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. ⛩️📰 书社 copies 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 ⛩️📰 书社 name·space is `urn:fdc:ladys.computer:20231231:Shu1She4`.
94 This document uses a few name·space prefixes, with the following
97 | Prefix | Expansion |
98 | ---------: | :-------------------------------------------- |
99 | `catalog:` | `urn:oasis:names:tc:entity:xmlns:xml:catalog` |
100 | `exsl:` | `http://exslt.org/common` |
101 | `exslstr:` | `http://exslt.org/strings` |
102 | `html:` | `http://www.w3.org/1999/xhtml` |
103 | `svg:` | `http://www.w3.org/2000/svg` |
104 | `xlink:` | `http://www.w3.org/1999/xlink` |
105 | `xslt:` | `http://www.w3.org/1999/XSL/Transform` |
106 | `书社:` | `urn:fdc:ladys.computer:20231231:Shu1She4` |
108 ## Setup and Configuration
110 ⛩️📰 书社 depends on the following programs to run.
111 In every case, you may supply your own implementation by overriding the
112 corresponding (allcaps) variable (e·g, set `MKDIR` to supply your own
113 `mkdir` implementation).
123 - `git` (optional; set `GIT=` to disable)
126 - `mkdir` (requires support for `-p`)
128 - `od` (requires support for `-t x1`)
129 - `pax` (only when generating archives)
134 - `stat` (BSD *or* GNU)
137 - `tr` (requires support for `-d`)
138 - `uuencode` (requires support for `-m` and `-r`)
139 - `uudecode` (requires support for `-m` and `-r`)
140 - `xargs` (requires support for `-0`)
141 - `xmlcatalog` (provided by `libxml2`)
142 - `xmllint` (provided by `libxml2`)
143 - `xsltproc` (provided by `libxslt`)
145 The following additional variables can be used to control the behaviour
149 The location of the source files (default: `sources`).
150 Multiple source directories can be provided, so long as the same
151 file subpath doesn’t exist in more than one of them.
154 The location of source includes (default: `sources/includes`).
155 This can be inside of `SRCDIR`, but needn’t be.
156 Multiple include directories can be provided, so long as the same
157 file subpath doesn’t exist in more than one of them.
160 The location of the (temporary) build directory (default: `build`).
161 `make clean` will delete this, and it is recommended that it not be
162 used for programs aside from ⛩️📰 书社.
165 The location of directory to output files to (default: `public`).
166 `make install` will overwrite files in this directory which
167 correspond to those in `SRCDIR`.
168 It *will not* touch other files, including those generated from files
169 in `SRCDIR` which have since been deleted.
171 Files are first compiled to `$(BUILDDIR)/public` before they are
172 copied to `DESTDIR`, so this folder is relatively quick and
173 inexpensive to re·create.
174 It’s reasonable to simply delete it before every `make install` to
175 ensure stale content is removed.
178 The location of the ⛩️📰 书社 `GNUmakefile`.
179 This should be set automatically when calling Make and shouldn’t ever
180 need to be set manually.
181 This variable is used to find the ⛩️📰 书社 `lib/` folder, which is
182 expected to be in the same location.
185 A white·space‐separated list of magic files to use (default:
186 `$(THISDIR)/magic/*`).
189 The value of this variable is appended to `MAGIC` by default, to
190 enable additional magic files without overriding the existing ones.
193 Rules to use with `find` when searching for source files.
194 The default ignores files that start with a period or hyphen‐minus,
195 those which end with a cloparen, and those which contain a hash,
196 buck, percent, asterisk, colon, semi, eroteme, bracket, backslash,
199 - **`EXTRAFINDRULES`:**
200 The value of this variable is appended to `FINDRULES` by default, to
201 enable additional rules without overriding the existing ones.
203 - **`FINDINCLUDERULES`:**
204 Rules to use with `find` when searching for includes (default:
207 - **`EXTRAFINDINCLUDERULES`:**
208 The value of this variable is appended to `FINDINCLUDERULES` by
209 default, to enable additional rules without overriding the existing
213 A white·space‐separated list of parsers to use (default:
214 `$(THISDIR)/parsers/*.xslt`).
216 - **`EXTRAPARSERS`:**
217 The value of this variable is appended to `PARSERS` by default, to
218 enable additional parsers without overriding the existing ones.
221 A white·space‐separated list of transforms to use (default:
222 `$(THISDIR)/transforms/*.xslt`).
224 - **`EXTRATRANSFORMS`:**
225 The value of this variable is appended to `TRANSFORMS` by default, to
226 enable additional transforms without overriding the existing ones.
229 A white·space‐separated list of media types to consider X·M·L
230 (default: `application/xml text/xml`).
233 The current version of ⛩️📰 书社 (default: derived from the current
234 git tag/branch/commit).
237 The current version of the source files (default: derived from the
238 current git tag/branch/commit).
241 If this variable has a value, every recipe instruction will be
242 printed when it runs (default: empty).
243 This is helpful for debugging, but typically too noisy for general
248 Source files may be placed in `SRCDIR` in any manner; the file
249 structure used there will match the output.
250 The type of source files is *not* determined by file extension, but
251 rather by magic number; this means that files **must** begin with
252 something recognizable.
253 Supported magic numbers include :—
255 - `<?xml` for `application/xml` files
256 - `#!js` for `text/javascript` files
257 - `@charset "` for `text/css` files
258 - `#!tsv` for `text/tab-separated-values` files
259 - `%%` for `text/record-jar` files (unregistered; see
260 [[draft-phillips-record-jar-01][]])
262 Text formats with associated X·S·L·T parsers are wrapped in a H·T·M·L
263 `<script>` element whose `@type` gives its media type, and then
264 passed to the parser to process.
265 Source files whose media type does not have an associated X·S·L·T
266 parser are considered “assets” and will not be transformed.
268 **☡ For compatibility with this program, source file·names must not
269 contain Ascii white·space, colons (`:`), semis (`;`), pipes (`|`),
270 bucks (`$`), percents (`%`), hashes (`#`), asterisks (`*`), brackets
271 (`[` or `]`), erotemes (`?`), backslashes (`\`), or control
272 characters, must not begin with a hyphen‐minus (`-`), and must not
273 end with a cloparen (`)`).**
274 The former characters have the potential to conflict with make syntax,
275 a leading hyphen‐minus is confusable for a command‐line argument, and
276 a trailing cloparen [activates a bug in G·N·U Make
277 3.81](https://stackoverflow.com/questions/17148468/capturing-filenames-including-parentheses-with-gnu-makes-wildcard-function#comment24825307_17148894).
281 Parsers are used to convert plaintext files into X·M·L trees, as well
282 as convert plaintext formats which are already included inline in
283 existing source X·M·L documents.
284 ⛩️📰 书社 comes with some parsers; namely :—
286 - **`parsers/plain.xslt`:**
287 Wraps `text/plain` contents in a `<html:pre>` element.
289 - **`parsers/record-jar.xslt`:**
290 Converts `text/record-jar` contents into a `<html:div>` of
291 `<html:dl>` elements (one for each record).
293 - **`parsers/tsv.xslt`:**
294 Converts `text/tab-separated-values` contents into an `<html:table>`
297 New ⛩️📰 书社 parsers which target plaintext formats should have an
298 `<xslt:template>` element with no `@name` or `@mode` and whose
301 - Starts with an appropriately‐name·spaced qualified name for a
302 `<html:script>` element.
304 - Follows this with the string `[@type=`.
306 - Follows this with a quoted string giving a media type supported by
308 Media type parameters are *not* supported.
310 - Follows this with the string `]`.
312 For example, the trivial `text/plain` parser is defined as follows :—
315 <?xml version="1.0"?>
317 xmlns="http://www.w3.org/1999/XSL/Transform"
318 xmlns:html="http://www.w3.org/1999/xhtml"
319 xmlns:书社="urn:fdc:ladys.computer:20231231:Shu1She4"
322 <书社:id>example:text/plain</书社:id>
323 <template match="html:script[@type='text/plain']">
324 <html:pre><value-of select="."/></html:pre>
329 ⛩️📰 书社 will scan the provided parsers for this pattern to determine
330 the set of allowed plaintext file types.
331 Multiple such `<xslt:template>` elements may be provided in a single
332 parser, for example if the parser supports multiple media types.
333 Alternatively, you can set the `@书社:supported-media-types` attribute
334 on the root element of the parser to override media type support
337 Even when `@书社:supported-media-types` is set, it is a requirement
338 that each parser transform any `<html:script>` elements with a
339 `@type` which matches their registered types into something else.
340 Otherwise the parser will be stuck in an endless loop.
341 The result tree of applying the transform to the `<html:script>`
342 element will be reparsed (in case any new `<html:script>` elements
343 were added in its subtree), and a `@书社:parsed-by` attribute will be
344 added to each toplevel element in the result.
345 The value of this attribute will be the value of the `<书社:id>`
346 toplevel element in the parser.
348 It is possible for parsers to support zero plaintext types.
349 This is useful when targeting specific dialects of X·M·L; parsers in
350 this sense operate on the same basic principles as transforms
352 The major distinction between X·M·L parsers and transforms is where in
353 the process the transformation happens:
354 Parsers are applied *prior* to embedding (and can be used to generate
355 embeds); transforms are applied *after*.
357 It is **strongly recommended** that auxillary templates in parsers be
358 name·spaced (by `@name` or `@mode`) whenever possible, to avoid
359 conflicts between parsers.
361 ### Attributes added during parsing
363 ⛩️📰 书社 will add a few attributes to the output of the parsing step,
366 - A `@书社:cksum` attribute on toplevel result elements, giving the
367 `cksum` checksum of the corresponding source file.
369 - For the elements which result from parsing plaintext `<html:script>`
372 - A `@书社:parsed-by` attribute, giving a space‐separated list of
373 parsers which parsed the node.
374 (Generally, this will be a list of one, but it is possible for the
375 result of a parse to be another plaintext node, which may be
376 parsed by a different parser.)
378 - A `@书社:media-type` attribute, giving the identified media type of
383 Documents can be embedded in other documents using a `<书社:link>`
384 element with `@xlink:show="embed"`.
385 The `@xlink:href`s of these elements should have the format
386 `about:shushe?source=<path>`, where `<path>` provides the path to the
387 file within `SRCDIR`.
388 Includes, which do not generate outputs of their own but may still be
389 freely embedded, instead use the format
390 `about:shushe?include=<path>`, where `<path>` provides the path
393 Embeds are replaced with the parsed contents of a file, unless the file
394 is an asset, in which case an `<html:object>` element is produced
395 instead (with the contents of the asset file provided as a base64
397 Embed replacements will be given a `@书社:identifier` attribute whose
398 value will match the `@xlink:href` of the embed.
400 Embedding takes place after parsing but before transformation, so
401 parsers are able to generate their own embeds.
402 ⛩️📰 书社 is able to detect the transitive embed dependencies of files
403 and update them accordingly; it will signal an error if the
404 dependencies are recursive.
406 ## Output Redirection
408 By default, ⛩️📰 书社 installs files to the same location in `DESTDIR`
409 as they were placed in their `SRCDIR`.
410 This behaviour can be customized by setting the `@书社:destination`
411 attribute on the root element, whose value can give a different path.
412 This attribute is read after parsing, but before transformation (where
413 it is silently dropped).
417 Transforms are used to convert X·M·L files into their final output,
418 after all necessary parsing and embedding has taken place.
419 ⛩️📰 书社 comes with some transforms; namely :—
421 - **`transforms/asset.xslt`:**
422 Converts `<html:object>` elements which correspond to recognized
423 media types into the appropriate H·T·M·L elements, and deletes
424 `<html:style>` elements from the body of the document and moves
427 - **`transforms/metadata.xslt`:**
428 Provides basic `<html:head>` metadata.
429 This metadata is generated from `<html:meta>` elements with one of
430 the following `@itemprop` attributes :—
432 - **`urn:fdc:ladys.computer:20231231:Shu1She4:title`:**
433 Provides the title of the page.
435 ⛩️📰 书社 automatically encapsulates H·T·M·L embeds so that their
436 metadata does not propogate up to the embedding document.
437 To undo this behaviour, remove the `@itemscope` and `@itemtype`
438 attributes from the embed during the transformation phase.
440 - **`transforms/serialization.xslt`:**
441 Replaces `<书社:serialize-xml>` elements with the (escaped)
442 serialized X·M·L of their contents.
443 This replacement happens during the application phase, after most
444 other transformations have taken place.
446 If a `@with-namespaces` attribute is provided, any name·space nodes
447 on the toplevel serialized elements whose U·R·I’s correspond to the
448 definitions of the provided prefixes, as defined for the
449 `<书社:serialize-xml>` element, will be declared using name·space
450 attributes on the serialized elements.
451 Otherwise, only name·space nodes which _differ_ from the definitions
452 on the `<书社:serialize-xml>` element will be declared.
453 The string `#default` may be used to represent the default
455 Multiple prefixes may be provided, separated by white·space.
457 When it comes to name·spaces used internally by ⛩️📰 书社, the
458 prefix used by ⛩️📰 书社 may be declared _in addition to_ the
459 prefix(es) used in the source document(s).
460 It is not possible to selectively only declare one prefix for a
461 name·space to the exclusion of others.
463 `<书社:raw-output>` elements may be used inside of
464 `<书社:serialize-xml>` elements to inject raw output into the
467 The following are recommendations on effective creation of
470 - Make template matchers as specific as possible.
471 It is likely an error if two transforms have templates which match
472 the same element (unless the templates have different priority).
474 - Name·space templates (with `@name` or `@mode`) whenever possible.
476 - Set `@exclude-result-prefixes` on the root `xslt:transform` element
477 to reduce the number of declared name·spaces in the final result.
481 The following params are made available globally in parsers and
488 The checksum of the source file (⅌ `cksum`).
491 The ⛩️📰 书社 identifier of the source file (a u·r·i beginning with
495 The value of the `SRCREV` variable (if present).
498 The time at which the source file was last modified.
501 The value of the `THISREV` variable (if present).
503 The following params are only available in transforms :—
506 The path of the catalog file (within `BUILDDIR`).
509 The path of the output file (within `DESTDIR`).
513 ⛩️📰 书社 will wrap the final output of the transforms in appropriate
514 `<html:html>` and `<html:body>` elements, so it is not necessary for
515 transforms to do this explicitly.
516 After performing the initial transform, ⛩️📰 书社 will match the root
517 node of the result in the following modes to fill in areas of the
521 The result of matching in this mode is prepended into the
522 `<html:body>` of the output (before the transformation result).
525 The result of matching in this mode is appended into the
526 `<html:body>` of the output (after the transformation result).
529 The result of matching in this mode is inserted into the
530 `<html:head>` of the output.
532 In addition to being called with the transform result, each of these
533 modes will additionally be called with a `<xslt:include>` element
534 corresponding to each transform.
535 If a transform has a `<书社:id>` top‐level element whose value is an
536 i·r·i, its `<xslt:include>` element will have a corresponding
538 This mechanism can be used to allow transforms to insert content
539 without matching any elements in the result; for example, the
540 following transform adds a link to a stylesheet to the `<html:head>`
544 <?xml version="1.0"?>
546 xmlns="http://www.w3.org/1999/XSL/Transform"
547 xmlns:html="http://www.w3.org/1999/xhtml"
548 xmlns:xslt="http://www.w3.org/1999/XSL/Transform"
549 xmlns:书社="urn:fdc:ladys.computer:20231231:Shu1She4"
550 exclude-result-prefixes="书社"
553 <书社:id>example:add-stylesheet-links.xslt</书社:id>
554 <template match="xslt:include[@书社:id='example:add-stylesheet-links.xslt']" mode="书社:metadata">
555 <html:link rel="stylesheet" type="text/css" href="/style.css"/>
560 Output wrapping can be entirely disabled by adding a
561 `@书社:disable-output-wrapping` attribute to the top‐level element in
563 It will not be performed on outputs whose root elements are
564 `<书社:archive>`, `<书社:base64-binary>`, or `<书社:raw-text>`
567 ## Applying Attributes
569 The `<书社:apply-attributes>` element will apply any attributes on the
570 element to the element(s) it wraps.
571 It is especially useful in combination with embeds.
573 The `<书社:apply-attributes-to-root>` element will apply any attributes
574 on the element to the root node of the final transformation result.
575 It is especially useful in combination with output wrapping.
577 In both cases, attributes from various sources are combined with
578 white·space between them.
579 Attribute application takes place after all ordinary transforms have
582 Both elements ignore attributes in the `xml:` name·space, except for
583 `@xml:lang`, which ignores all but the first definition (including
584 any already present on the root element).
585 On H·T·M·L and S·V·G elements, `@lang` has the same behaviour as
588 ## Other Kinds of Output
590 There are a few special elements in the `书社:` name·space which, if
591 they appear as the toplevel element in a transformation result, cause
592 ⛩️📰 书社 to produce something other than an X·M·L file.
595 - **`<书社:archive>`:**
596 Each child element with a `@书社:archived-as` attribute will be
597 archived as a separate file in a resulting tarball (this attribute
598 gives the file name).
599 These elements will be processed the same as the root elements of any
600 other file (e·g, they will be wrapped; they can themselves specify
601 non X·M·L output types, ⁊·c).
602 Other child elements will be ignored.
604 - **`<书社:base64-binary>`:**
605 The text nodes in the transformation result will, after removing all
606 Ascii whitespace, be treated as a Base·64 string, which is then
609 - **`<书社:raw-text>`:**
610 A plaintext (U·T·F‐8) file will be produced from the text nodes in
611 the transformation result.
615 This repository conforms to [REUSE][].
617 Most source files are licensed under the terms of the <cite>Mozilla
618 Public License, version 2.0</cite>.
620 [REUSE]: <https://reuse.software/spec/>
621 [draft-phillips-record-jar-01]: <https://datatracker.ietf.org/doc/html/draft-phillips-record-jar-01>