3 <b>An X·S·L·T‐based static site generator.</b>
5 <dfn>⛩️📰 书社</dfn> aims to make it easy to generate websites with
6 X·S·L·T and G·N·U Make.
7 It is consequently only a good choice for people who like X·S·L·T and
8 G·N·U Make and wish it were easier to make websites with them.
10 It makes things easier by :—
12 - Automatically identifying source files and characterizing them by
13 type (X·M·L, text, or asset).
15 - Parsing supported text types into X·M·L trees.
17 - Enabling easy inclusion of source files within each other.
19 It aims to do this with zero dependencies beyond the programs already
20 installed on your computer.
24 <i lang="cmn-Hans">书社</i> is a Chinese word meaning “publishing
27 The first character, <i lang="cmn-Hans">书</i>, is the simplified form
30 The second character, <i lang="cmn-Hans">社</i>, contemporarily means
31 “association”, but historically referred to the god of the soil and
32 related altars or festivities.
33 In Japanese, it is an alternate spelling for <i lang="ja">やしろ</i>,
34 the word for “Shinto shrine”.
36 The name <i lang="cmn-Hans">书社</i> was chosen to play on this pun, as
37 it is intended as a publishing program for webshrines.
39 In Ascii environments, ⛩️📰 书社 should be written `Shushe`, following
40 the pinyin transliteration.
44 Place source files in `sources/` and run `make install` to compile
45 the result to `public/`.
46 Compilation involves the following steps :—
48 1. ⛩️📰 书社 compiles all of the magic files in `magic/` into a single
49 file, `build/magic.mgc`.
51 2. ⛩️📰 书社 processes all of the parsers in `parsers/` and determines
52 the list of supported plaintext types.
54 3. ⛩️📰 书社 identifies all of the source files and includes and uses
55 `build/magic.mgc` to classify them by media type.
57 4. ⛩️📰 书社 parses all plaintext and X·M·L source files and includes
58 and then builds a dependency tree between them.
60 5. ⛩️📰 书社 uses the dependency tree to establish prerequisites for
63 6. ⛩️📰 书社 compiles each output file to `build/public`.
65 7. ⛩️📰 书社 copies the output files to `public`.
67 You can use `make list` to list each identified source file or include
68 alongside its computed type and dependencies.
69 As this is a Make‐based program, steps will only be run if the
70 corresponding buildfile or output file is older than its
75 The ⛩️📰 书社 namespace is `urn:fdc:ladys.computer:20231231:Shu1She4`.
77 This document uses a few namespace prefixes, with the following
80 | Prefix | Expansion |
81 | -------: | :----------------------------------------- |
82 | `html:` | `http://www.w3.org/1999/xhtml` |
83 | `xlink:` | `http://www.w3.org/1999/xlink` |
84 | `xslt:` | `http://www.w3.org/1999/XSL/Transform` |
85 | `书社:` | `urn:fdc:ladys.computer:20231231:Shu1She4` |
87 ## Setup and Configuration
89 ⛩️📰 书社 depends on the following programs to run.
90 In every case, you may supply your own implementation by overriding the
91 corresponding (allcaps) variable (e·g, set `MKDIR` to supply your own
92 `mkdir` implementation).
100 - `mkdir` (requires support for `-p`)
109 - `tr` (requires support for `-d`)
110 - `uuencode` (requires support for `-m` and `-r`)
111 - `xmlcatalog` (provided by `libxml2`)
112 - `xmllint` (provided by `libxml2`)
113 - `xsltproc` (provided by `libxslt`)
115 The following additional variables can be used to control the behaviour
119 The location of the source files (default: `sources`).
122 The location of the source files (default: `sources/includes`).
123 This can be inside of `SRCDIR`, but needn’t be.
126 The location of the (temporary) build directory (default: `build`).
129 The location of directory to output files to (default: `public`).
132 The location of the ⛩️📰 书社 `GNUmakefile`.
133 This should be set automatically when calling Make and shouldn’t ever
134 need to be set manually.
135 This variable is used to find the ⛩️📰 书社 `lib/` folder, which is
136 expected to be in the same location.
139 The location of the magic files to use (default: `$(THISDIR)/magic`).
142 Options to pass to `find` when searching for source files (default:
146 Rules to use with `find` when searching for source files (default:
147 `-flags -nohidden -and -not -name '.*'`).
150 A white·space‐separated list of parsers to use (default:
151 `$(THISDIR)/parsers/*.xslt`).
154 A white·space‐separated list of transforms to use (default:
155 `$(THISDIR)/transforms/*.xslt`).
158 A white·space‐separated list of media types to consider X·M·L
159 (default: `application/xml text/xml`).
162 If this variable has a value, every recipe instruction will be
163 printed when it runs (default: empty).
164 This is helpful for debugging, but typically too noisy for general
169 Source files may be placed in `SRCDIR` in any manner; the file
170 structure used there will match the output.
171 The type of source files is *not* determined by file extension, but
172 rather by magic number; this means that files **must** begin with
173 something recognizable.
174 Supported magic numbers include :—
176 - `<?xml` for `application/xml` files
177 - `#!js` for `text/javascript` files
178 - `@charset "` for `text/css` files
179 - `#!tsv` for `text/tab-separated-values` files
180 - `%%` for `text/record-jar` files (unregistered; see
181 [[draft-phillips-record-jar-01][]])
183 Text formats with associated X·S·L·T parsers are wrapped in a H·T·M·L
184 `<script>` element whose `@type` gives its media type, and then
185 passed to the parser to process.
186 Source files whose media type does not have an associated X·S·L·T
187 parser are considered “assets” and will not be transformed.
189 For compatibility with this program, source filenames should conform to
190 the following rules :—
192 - They should not start with a hyphen‐minus.
193 This is to prevent confusion between filenames and options on the
196 - They should not contain spaces, colons, percent signs, backticks,
197 question marks, hashes, or backslashes.
199 In general, filenames should be such that they do not require
200 percent‐encoding in the path component of an i·r·i.
204 Parsers are used to convert plaintext files into X·M·L trees, as well
205 as convert plaintext formats which are already included inline in
206 existing source X·M·L documents.
207 ⛩️📰 书社 comes with some parsers; namely :—
209 - **`parsers/plain.xslt`:**
210 Wraps `text/plain` contents in a `<html:pre>` element.
212 - **`parsers/tsv.xslt`:**
213 Converts `text/tab-separated-values` contents into an `<html:table>`
216 New ⛩️📰 书社 parsers should have a `<xslt:template>` element with no
217 `@name` or `@mode` and whose `@match` attribute…
219 - Starts with an appropriately‐namespaced qualified name for a
220 `<html:script>` element.
222 - Follows this with the string `[@type=`.
224 - Follows this with a quoted string giving a media type supported by
226 Media type parameters are *not* supported.
228 - Follows this with the string `]`.
230 For example, the trivial `text/plain` parser is defined as follows :—
233 <?xml version="1.0"?>
235 xmlns="http://www.w3.org/1999/XSL/Transform"
236 xmlns:html="http://www.w3.org/1999/xhtml"
239 <template match="html:script[@type='text/plain']">
240 <html:pre><value-of select="."/></html:pre>
245 ⛩️📰 书社 will scan the provided parsers for this pattern to determine
246 the set of allowed plaintext file types.
247 Multiple such `<xslt:template>` elements may be provided in a single
248 parser, for example if the parser supports multiple media types.
249 Alternatively, you can set the `@书社:supported-media-types` attribute
250 on the root element of the parser to override media type support
253 It is **strongly recommended** that all templates in parsers other than
254 those described above be namespaced (by `@name` or `@mode`), to avoid
255 conflicts between templates in multiple parsers.
259 Documents can be embedded in other documents using a `<书社:link>`
260 element with `@xlink:show="embed"`.
261 The `@xlink:href`s of these elements should have the format
262 `about:shushe?source=<path>`, where `<path>` provides the path to the
263 file within `SRCDIR`.
264 Includes, which do not generate outputs of their own but may still be
265 freely embedded, instead use the format
266 `about:shushe?include=<path>`, where `<path>` provides the path
269 Embeds are replaced with the parsed contents of a file, unless the file
270 is an asset, in which case an `<html:object>` element is produced
271 instead (with the contents of the asset file provided as a base64
274 Embedding takes place after parsing but before transformation, so
275 parsers are able to generate their own embeds.
276 ⛩️📰 书社 is able to detect the transitive embed dependencies of files
277 and update them accordingly; it will signal an error if the
278 dependencies are recursive.
282 Transforms are used to convert X·M·L files into their final output,
283 after all necessary parsing and embedding has taken place.
284 ⛩️📰 书社 comes with some transforms; namely :—
286 - **`transforms/asset.xslt`:**
287 Converts `<html:object>` elements which correspond to recognized
288 media types into the appropriate H·T·M·L elements, and deletes
289 `<html:style>` elements from the body of the document and moves
292 - **`transforms/metadata.xslt`:**
293 Provides basic `<html:head>` metadata.
294 This metadata is generated from `<html:meta>` elements with one o.
295 the following `@itemprop` attributes :—
297 - **`urn:fdc:ladys.computer:20231231:Shu1She4:title`:**
298 Provides the title of the page.
300 ⛩️📰 书社 automatically encapsulates embeds so that their metadata
301 does not propogate up to the embedding document.
302 To undo this behaviour, remove the `@itemscope` and `@itemtype`
303 attributes from the embed during the transformation phase.
305 The following are recommendations on effective creation of
308 - Make template matchers as specific as possible.
309 It is likely an error if two transforms have templates which match
310 the same element (unless the templates have different priority).
312 - Namespace templates (with `@name` or `@mode`) whenever possible.
314 - Set `@exclude-result-prefixes` on the root `xslt:transform` element
315 to reduce the number of declared namespaces in the final result.
317 The params `$buildtime`, `$srctime`, and `$path` are available within
318 transforms and are initialized to the current time, the time that the
319 source file was last modified, and the path of the output file within
324 ⛩️📰 书社 will wrap the final output of the transforms in appropriate
325 `<html:html>` and `<html:body>` elements, so it is not necessary for
326 transforms to do this explicitly.
327 After performing the initial transform, ⛩️📰 书社 will match the root
328 node of the result in the following modes to fill in areas of the
332 The result of matching in this mode is prepended into the
333 `<html:body>` of the output (before the transformation result).
336 The result of matching in this mode is appended into the
337 `<html:body>` of the output (after the transformation result).
340 The result of matching in this mode is inserted into the
341 `<html:head>` of the output.
343 In addition to being called with the transform result, each of these
344 modes will additionally be called with a `<xslt:include>` element
345 corresponding to each transform.
346 If a transform has a `<书社:id>` top‐level element whose value is an
347 i·r·i, its `<xslt:import>` element will have a corresponding
349 This mechanism can be used to allow transforms to insert content
350 without matching any elements in the result; for example, the
351 following transform adds a link to a stylesheet to the `<html:head>`
355 <?xml version="1.0"?>
357 xmlns="http://www.w3.org/1999/XSL/Transform"
358 xmlns:html="http://www.w3.org/1999/xhtml"
359 xmlns:xslt="http://www.w3.org/1999/XSL/Transform"
360 xmlns:书社="urn:fdc:ladys.computer:20231231:Shu1She4"
361 exclude-result-prefixes="书社"
364 <书社:id>example:add-stylesheet-links.xslt</书社:id>
365 <template match="xslt:include[@书社:id='example:add-stylesheet-links.xslt']" mode="书社:metadata">
366 <html:link rel="stylesheet" type="text/css" href="/style.css"/>
371 Output wrapping can be entirely disabled by adding a
372 `@书社:disable-output-wrapping` attribute to the top‐level element in
377 Source files are licensed under the terms of the <cite>Mozilla Public
378 License, version 2.0</cite>.
379 For more information, see [LICENSE](./LICENSE).
381 [draft-phillips-record-jar-01]: <https://datatracker.ietf.org/doc/html/draft-phillips-record-jar-01>