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