]> Lady’s Gitweb - Shushe/blob - README.markdown
Reduce subshells created by percent·encoding
[Shushe] / README.markdown
1 # ⛩️📰 书社
2
3 <b>A make·file for X·M·L.</b>
4
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.
9
10 It makes things easier by :⁠—
11
12 - Automatically identifying source files and characterizing them by
13 type (X·M·L, text, or asset).
14
15 - Parsing supported text types into X·M·L trees.
16
17 - Enabling easy inclusion of source files within each other.
18
19 It aims to do this with zero dependencies beyond the programs already
20 installed on your computer.
21 (On Linux machines, you may need to install `libxml2-utils` to get the
22 commandline programs from `libxml2`.)
23
24 **Note:**
25 ⛩️📰 书社 requires functionality present in G·N·U Make 3.81 (or later)
26 and will not work in previous versions, or other implementations of
27 Make.
28 Compatibility with later versions of G·N·U Make is assumed, but not
29 tested.
30
31 ## Nomenclature
32
33 <i lang="cmn-Hans">书社</i> is a Chinese word meaning “publishing
34 house”.
35
36 The first character, <i lang="cmn-Hans">书</i>, is the simplified form
37 of “document”.
38
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”.
44
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.
47
48 In Ascii environments, ⛩️📰 书社 should be written `Shushe`, following
49 the pinyin transliteration.
50
51 ## Basic Usage
52
53 Place source files in `sources/` and run `make install` to compile
54 the result to `public/`.
55 Compilation involves the following steps :⁠—
56
57 1. ⛩️📰 书社 compiles all of the magic files in `magic/` into a single
58 file, `build/magic.mgc`.
59
60 2. ⛩️📰 书社 processes all of the parsers in `parsers/` and determines
61 the list of supported plaintext types.
62
63 3. ⛩️📰 书社 identifies all of the source files and includes and uses
64 `build/magic.mgc` to classify them by media type.
65
66 4. ⛩️📰 书社 parses all plaintext and X·M·L source files and includes
67 and then builds a dependency tree between them.
68
69 5. ⛩️📰 书社 uses the dependency tree to establish prerequisites for
70 each output file.
71
72 6. ⛩️📰 书社 compiles each output file to `build/public`.
73
74 7. ⛩️📰 书社 copies the output files to `public`.
75
76 You can use `make list` to list each identified source file or include
77 alongside its computed type and dependencies.
78 As this is a Make‐based program, steps will only be run if the
79 corresponding buildfile or output file is older than its
80 prerequisites.
81
82 ## Namespaces
83
84 The ⛩️📰 书社 namespace is `urn:fdc:ladys.computer:20231231:Shu1She4`.
85
86 This document uses a few namespace prefixes, with the following
87 meanings :⁠—
88
89 | Prefix | Expansion |
90 | -------: | :----------------------------------------- |
91 | `html:` | `http://www.w3.org/1999/xhtml` |
92 | `xlink:` | `http://www.w3.org/1999/xlink` |
93 | `xslt:` | `http://www.w3.org/1999/XSL/Transform` |
94 | `书社:` | `urn:fdc:ladys.computer:20231231:Shu1She4` |
95
96 ## Setup and Configuration
97
98 ⛩️📰 书社 depends on the following programs to run.
99 In every case, you may supply your own implementation by overriding the
100 corresponding (allcaps) variable (e·g, set `MKDIR` to supply your own
101 `mkdir` implementation).
102
103 - `awk`
104 - `cat`
105 - `cp`
106 - `date`
107 - `echo`
108 - `file`
109 - `find`
110 - `git` (optional; set `GIT=` to disable)
111 - `ln`
112 - `mkdir` (requires support for `-p`)
113 - `mv`
114 - `od` (requires support for `-t x1`)
115 - `printf`
116 - `rm`
117 - `sed`
118 - `sleep`
119 - `stat`
120 - `test`
121 - `touch`
122 - `tr` (requires support for `-d`)
123 - `uuencode` (requires support for `-m` and `-r`)
124 - `xargs` (requires support for `-0`)
125 - `xmlcatalog` (provided by `libxml2`)
126 - `xmllint` (provided by `libxml2`)
127 - `xsltproc` (provided by `libxslt`)
128
129 The following additional variables can be used to control the behaviour
130 of ⛩️📰 书社 :⁠—
131
132 - **`SRCDIR`:**
133 The location of the source files (default: `sources`).
134 Multiple source directories can be provided, so long as the same
135 file subpath doesn’t exist in more than one of them.
136
137 - **`INCLUDEDIR`:**
138 The location of source includes (default: `sources/includes`).
139 This can be inside of `SRCDIR`, but needn’t be.
140 Multiple include directories can be provided, so long as the same
141 file subpath doesn’t exist in more than one of them.
142
143 - **`BUILDDIR`:**
144 The location of the (temporary) build directory (default: `build`).
145 `make clean` will delete this, and it is recommended that it not be
146 used for programs aside from ⛩️📰 书社.
147
148 - **`DESTDIR`:**
149 The location of directory to output files to (default: `public`).
150 `make install` will overwrite files in this directory which
151 correspond to those in `SRCDIR`.
152 It *will not* touch other files, including those generated from files
153 in `SRCDIR` which have since been deleted.
154
155 Files are first compiled to `$(BUILDDIR)/public` before they are
156 copied to `DESTDIR`, so this folder is relatively quick and
157 inexpensive to re·create.
158 It’s reasonable to simply delete it before every `make install` to
159 ensure stale content is removed.
160
161 - **`THISDIR`:**
162 The location of the ⛩️📰 书社 `GNUmakefile`.
163 This should be set automatically when calling Make and shouldn’t ever
164 need to be set manually.
165 This variable is used to find the ⛩️📰 书社 `lib/` folder, which is
166 expected to be in the same location.
167
168 - **`MAGIC`:**
169 A white·space‐separated list of magic files to use (default:
170 `$(THISDIR)/magic/*`).
171
172 - **`EXTRAMAGIC`:**
173 The value of this variable is appended to `MAGIC` by default, to
174 enable additional magic files without overriding the existing ones.
175
176 - **`FINDRULES`:**
177 Rules to use with `find` when searching for source files.
178 The default ignores files that start with a period or hyphen‐minus,
179 those which end with a cloparen, and those which contain a hash,
180 buck, percent, asterisk, colon, semi, eroteme, bracket, backslash,
181 or pipe.
182
183 - **`EXTRAFINDRULES`:**
184 The value of this variable is appended to `FINDRULES` by default, to
185 enable additional rules without overriding the existing ones.
186
187 - **`FINDINCLUDERULES`:**
188 Rules to use with `find` when searching for includes (default:
189 `$(FINDRULES)`).
190
191 - **`EXTRAFINDINCLUDERULES`:**
192 The value of this variable is appended to `FINDINCLUDERULES` by
193 default, to enable additional rules without overriding the existing
194 ones.
195
196 - **`PARSERS`:**
197 A white·space‐separated list of parsers to use (default:
198 `$(THISDIR)/parsers/*.xslt`).
199
200 - **`EXTRAPARSERS`:**
201 The value of this variable is appended to `PARSERS` by default, to
202 enable additional parsers without overriding the existing ones.
203
204 - **`TRANSFORMS`:**
205 A white·space‐separated list of transforms to use (default:
206 `$(THISDIR)/transforms/*.xslt`).
207
208 - **`EXTRATRANSFORMS`:**
209 The value of this variable is appended to `TRANSFORMS` by default, to
210 enable additional transforms without overriding the existing ones.
211
212 - **`XMLTYPES`:**
213 A white·space‐separated list of media types to consider X·M·L
214 (default: `application/xml text/xml`).
215
216 - **`GENERATOR`:**
217 The name of the generator program (default: `⛩️📰 书社`).
218
219 - **`VERSION`:**
220 The current version of `GENERATOR` (default: derived from the current
221 git tag/branch/commit).
222
223 - **`SRCREV`:**
224 The current version of the source files (default: derived from the
225 current git tag/branch/commit).
226
227 - **`VERBOSE`:**
228 If this variable has a value, every recipe instruction will be
229 printed when it runs (default: empty).
230 This is helpful for debugging, but typically too noisy for general
231 usage.
232
233 ## Source Files
234
235 Source files may be placed in `SRCDIR` in any manner; the file
236 structure used there will match the output.
237 The type of source files is *not* determined by file extension, but
238 rather by magic number; this means that files **must** begin with
239 something recognizable.
240 Supported magic numbers include :⁠—
241
242 - `<?xml` for `application/xml` files
243 - `#!js` for `text/javascript` files
244 - `@charset "` for `text/css` files
245 - `#!tsv` for `text/tab-separated-values` files
246 - `%%` for `text/record-jar` files (unregistered; see
247 [[draft-phillips-record-jar-01][]])
248
249 Text formats with associated X·S·L·T parsers are wrapped in a H·T·M·L
250 `<script>` element whose `@type` gives its media type, and then
251 passed to the parser to process.
252 Source files whose media type does not have an associated X·S·L·T
253 parser are considered “assets” and will not be transformed.
254
255 **☡ For compatibility with this program, source file·names must not
256 contain Ascii white·space, colons (`:`), semis (`;`), pipes (`|`),
257 bucks (`$`), percents (`%`), hashes (`#`), asterisks (`*`), brackets
258 (`[` or `]`), erotemes (`?`), backslashes (`\`), or control
259 characters, must not begin with a hyphen‐minus (`-`), and must not
260 end with a cloparen (`)`).**
261 The former characters have the potential to conflict with make syntax,
262 a leading hyphen‐minus is confusable for a command‐line argument, and
263 a trailing cloparen [activates a bug in G·N·U Make
264 3.81](https://stackoverflow.com/questions/17148468/capturing-filenames-including-parentheses-with-gnu-makes-wildcard-function#comment24825307_17148894).
265
266 ## Parsers
267
268 Parsers are used to convert plaintext files into X·M·L trees, as well
269 as convert plaintext formats which are already included inline in
270 existing source X·M·L documents.
271 ⛩️📰 书社 comes with some parsers; namely :⁠—
272
273 - **`parsers/plain.xslt`:**
274 Wraps `text/plain` contents in a `<html:pre class="plain">` element.
275
276 - **`parsers/record-jar.xslt`:**
277 Converts `text/record-jar` contents into a
278 `<html:div class="record-jar">` of `<html:dl>` elements (one for
279 each record).
280
281 - **`parsers/tsv.xslt`:**
282 Converts `text/tab-separated-values` contents into an
283 `<html:table class="tsv">` element.
284
285 New ⛩️📰 书社 parsers which target plaintext formats should have an
286 `<xslt:template>` element with no `@name` or `@mode` and whose
287 `@match` attribute…
288
289 - Starts with an appropriately‐namespaced qualified name for a
290 `<html:script>` element.
291
292 - Follows this with the string `[@type=`.
293
294 - Follows this with a quoted string giving a media type supported by
295 the parser.
296 Media type parameters are *not* supported.
297
298 - Follows this with the string `]`.
299
300 For example, the trivial `text/plain` parser is defined as follows :⁠—
301
302 ```xml
303 <?xml version="1.0"?>
304 <transform
305 xmlns="http://www.w3.org/1999/XSL/Transform"
306 xmlns:html="http://www.w3.org/1999/xhtml"
307 xmlns:书社="urn:fdc:ladys.computer:20231231:Shu1She4"
308 version="1.0"
309 >
310 <书社:id>example:text/plain</书社:id>
311 <template match="html:script[@type='text/plain']">
312 <html:pre><value-of select="."/></html:pre>
313 </template>
314 </transform>
315 ```
316
317 ⛩️📰 书社 will scan the provided parsers for this pattern to determine
318 the set of allowed plaintext file types.
319 Multiple such `<xslt:template>` elements may be provided in a single
320 parser, for example if the parser supports multiple media types.
321 Alternatively, you can set the `@书社:supported-media-types` attribute
322 on the root element of the parser to override media type support
323 detection.
324
325 Even when `@书社:supported-media-types` is set, it is a requirement
326 that each parser transform any `<html:script>` elements with a
327 `@type` which matches their registered types into something else.
328 Otherwise the parser will be stuck in an endless loop.
329 The result tree of applying the transform to the `<html:script>`
330 element will be reparsed (in case any new `<html:script>` elements
331 were added in its subtree), and a `@书社:parsed-by` attribute will be
332 added to each toplevel element in the result.
333 The value of this attribute will be the value of the `<书社:id>`
334 toplevel element in the parser.
335
336 It is possible for parsers to support zero plaintext types.
337 This is useful when targeting specific dialects of X·M·L; parsers in
338 this sense operate on the same basic principles as transforms
339 (described below).
340 The major distinction between X·M·L parsers and transforms is where in
341 the process the transformation happens:
342 Parsers are applied *prior* to embedding (and can be used to generate
343 embeds); transforms are applied *after*.
344
345 It is **strongly recommended** that auxillary templates in parsers be
346 namespaced (by `@name` or `@mode`) whenever possible, to avoid
347 conflicts between parsers.
348
349 ## Embedding
350
351 Documents can be embedded in other documents using a `<书社:link>`
352 element with `@xlink:show="embed"`.
353 The `@xlink:href`s of these elements should have the format
354 `about:shushe?source=<path>`, where `<path>` provides the path to the
355 file within `SRCDIR`.
356 Includes, which do not generate outputs of their own but may still be
357 freely embedded, instead use the format
358 `about:shushe?include=<path>`, where `<path>` provides the path
359 within `INCLUDEDIR`.
360
361 Embeds are replaced with the parsed contents of a file, unless the file
362 is an asset, in which case an `<html:object>` element is produced
363 instead (with the contents of the asset file provided as a base64
364 `data:` u·r·i).
365
366 Embedding takes place after parsing but before transformation, so
367 parsers are able to generate their own embeds.
368 ⛩️📰 书社 is able to detect the transitive embed dependencies of files
369 and update them accordingly; it will signal an error if the
370 dependencies are recursive.
371
372 ## Output Redirection
373
374 By default, ⛩️📰 书社 installs files to the same location in `DESTDIR`
375 as they were placed in their `SRCDIR`.
376 This behaviour can be customized by setting the `@书社:destination`
377 attribute on the root element, whose value can give a different path.
378 This attribute is read after parsing, but before transformation (where
379 it is silently dropped).
380
381 ## Transforms
382
383 Transforms are used to convert X·M·L files into their final output,
384 after all necessary parsing and embedding has taken place.
385 ⛩️📰 书社 comes with some transforms; namely :⁠—
386
387 - **`transforms/attributes.xslt`:**
388 Applies transforms to the children of any `<书社:apply-attributes>`
389 elements, and then applies the attributes of the
390 `<书社:apply-attributes>` to each result child, replacing the
391 element with the result.
392 This is useful in combination with image embeds to apply alt‐text to
393 the resulting `<html:img>`.
394
395 - **`transforms/asset.xslt`:**
396 Converts `<html:object>` elements which correspond to recognized
397 media types into the appropriate H·T·M·L elements, and deletes
398 `<html:style>` elements from the body of the document and moves
399 them to the head.
400
401 - **`transforms/metadata.xslt`:**
402 Provides basic `<html:head>` metadata.
403 This metadata is generated from `<html:meta>` elements with one of
404 the following `@itemprop` attributes :⁠—
405
406 - **`urn:fdc:ladys.computer:20231231:Shu1She4:title`:**
407 Provides the title of the page.
408
409 ⛩️📰 书社 automatically encapsulates embeds so that their metadata
410 does not propogate up to the embedding document.
411 To undo this behaviour, remove the `@itemscope` and `@itemtype`
412 attributes from the embed during the transformation phase.
413
414 The following are recommendations on effective creation of
415 transforms :⁠—
416
417 - Make template matchers as specific as possible.
418 It is likely an error if two transforms have templates which match
419 the same element (unless the templates have different priority).
420
421 - Namespace templates (with `@name` or `@mode`) whenever possible.
422
423 - Set `@exclude-result-prefixes` on the root `xslt:transform` element
424 to reduce the number of declared namespaces in the final result.
425
426 ## Global Params
427
428 The following params are made available globally in parsers and
429 transforms :⁠—
430
431 - **`BUILDTIME`:**
432 The current time.
433
434 - **`GENERATOR`:**
435 The value of the `GENERATOR` variable (if present).
436
437 - **`SRCREV`:**
438 The value of the `SRCREV` variable (if present).
439
440 - **`SRCTIME`:**
441 The time at which the source file was last modified.
442
443 - **`VERSION`:**
444 The value of the `VERSION` variable (if present).
445
446 The following params are only available in transforms :⁠—
447
448 - **`CATALOG`:**
449 The path of the catalog file (within `BUILDDIR`).
450
451 - **`PATH`:**
452 The path of the output file (within `DESTDIR`).
453
454 ## Output Wrapping
455
456 ⛩️📰 书社 will wrap the final output of the transforms in appropriate
457 `<html:html>` and `<html:body>` elements, so it is not necessary for
458 transforms to do this explicitly.
459 After performing the initial transform, ⛩️📰 书社 will match the root
460 node of the result in the following modes to fill in areas of the
461 wrapper :⁠—
462
463 - **`书社:header`:**
464 The result of matching in this mode is prepended into the
465 `<html:body>` of the output (before the transformation result).
466
467 - **`书社:footer`:**
468 The result of matching in this mode is appended into the
469 `<html:body>` of the output (after the transformation result).
470
471 - **`书社:metadata`:**
472 The result of matching in this mode is inserted into the
473 `<html:head>` of the output.
474
475 In addition to being called with the transform result, each of these
476 modes will additionally be called with a `<xslt:include>` element
477 corresponding to each transform.
478 If a transform has a `<书社:id>` top‐level element whose value is an
479 i·r·i, its `<xslt:include>` element will have a corresponding
480 `@书社:id` attribute.
481 This mechanism can be used to allow transforms to insert content
482 without matching any elements in the result; for example, the
483 following transform adds a link to a stylesheet to the `<html:head>`
484 of every page :⁠—
485
486 ```xml
487 <?xml version="1.0"?>
488 <transform
489 xmlns="http://www.w3.org/1999/XSL/Transform"
490 xmlns:html="http://www.w3.org/1999/xhtml"
491 xmlns:xslt="http://www.w3.org/1999/XSL/Transform"
492 xmlns:书社="urn:fdc:ladys.computer:20231231:Shu1She4"
493 exclude-result-prefixes="书社"
494 version="1.0"
495 >
496 <书社:id>example:add-stylesheet-links.xslt</书社:id>
497 <template match="xslt:include[@书社:id='example:add-stylesheet-links.xslt']" mode="书社:metadata">
498 <html:link rel="stylesheet" type="text/css" href="/style.css"/>
499 </template>
500 </transform>
501 ```
502
503 Output wrapping can be entirely disabled by adding a
504 `@书社:disable-output-wrapping` attribute to the top‐level element in
505 the result tree.
506
507 ## License
508
509 Source files are licensed under the terms of the <cite>Mozilla Public
510 License, version 2.0</cite>.
511 For more information, see [LICENSE](./LICENSE).
512
513 [draft-phillips-record-jar-01]: <https://datatracker.ietf.org/doc/html/draft-phillips-record-jar-01>
This page took 0.129214 seconds and 5 git commands to generate.