]> Lady’s Gitweb - Shushe/blob - README.markdown
81279a4dba7b8338a64074f4470a5d6fe8cd58e6
[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 and those which contain a hash, buck, percent, asterisk, colon,
180 semi, eroteme, bracket, backslash, or pipe.
181
182 - **`EXTRAFINDRULES`:**
183 The value of this variable is appended to `FINDRULES` by default, to
184 enable additional rules without overriding the existing ones.
185
186 - **`FINDINCLUDERULES`:**
187 Rules to use with `find` when searching for includes (default:
188 `$(FINDRULES)`).
189
190 - **`EXTRAFINDINCLUDERULES`:**
191 The value of this variable is appended to `FINDINCLUDERULES` by
192 default, to enable additional rules without overriding the existing
193 ones.
194
195 - **`PARSERS`:**
196 A white·space‐separated list of parsers to use (default:
197 `$(THISDIR)/parsers/*.xslt`).
198
199 - **`EXTRAPARSERS`:**
200 The value of this variable is appended to `PARSERS` by default, to
201 enable additional parsers without overriding the existing ones.
202
203 - **`TRANSFORMS`:**
204 A white·space‐separated list of transforms to use (default:
205 `$(THISDIR)/transforms/*.xslt`).
206
207 - **`EXTRATRANSFORMS`:**
208 The value of this variable is appended to `TRANSFORMS` by default, to
209 enable additional transforms without overriding the existing ones.
210
211 - **`XMLTYPES`:**
212 A white·space‐separated list of media types to consider X·M·L
213 (default: `application/xml text/xml`).
214
215 - **`VERBOSE`:**
216 If this variable has a value, every recipe instruction will be
217 printed when it runs (default: empty).
218 This is helpful for debugging, but typically too noisy for general
219 usage.
220
221 ## Source Files
222
223 Source files may be placed in `SRCDIR` in any manner; the file
224 structure used there will match the output.
225 The type of source files is *not* determined by file extension, but
226 rather by magic number; this means that files **must** begin with
227 something recognizable.
228 Supported magic numbers include :⁠—
229
230 - `<?xml` for `application/xml` files
231 - `#!js` for `text/javascript` files
232 - `@charset "` for `text/css` files
233 - `#!tsv` for `text/tab-separated-values` files
234 - `%%` for `text/record-jar` files (unregistered; see
235 [[draft-phillips-record-jar-01][]])
236
237 Text formats with associated X·S·L·T parsers are wrapped in a H·T·M·L
238 `<script>` element whose `@type` gives its media type, and then
239 passed to the parser to process.
240 Source files whose media type does not have an associated X·S·L·T
241 parser are considered “assets” and will not be transformed.
242
243 **☡ For compatibility with this program, source file·names must not
244 contain Ascii white·space, colons (`:`), semis (`;`), pipes (`|`),
245 bucks (`$`), percents (`%`), hashes (`#`), asterisks (`*`), brackets
246 (`[` or `]`), erotemes (`?`), backslashes (`\`), or control
247 characters, and must not begin with a hyphen‐minus (`-`).**
248 The former characters have the potential to conflict with make syntax,
249 and a leading hyphen‐minus is confusable for a command‐line argument.
250
251 ## Parsers
252
253 Parsers are used to convert plaintext files into X·M·L trees, as well
254 as convert plaintext formats which are already included inline in
255 existing source X·M·L documents.
256 ⛩️📰 书社 comes with some parsers; namely :⁠—
257
258 - **`parsers/plain.xslt`:**
259 Wraps `text/plain` contents in a `<html:pre class="plain">` element.
260
261 - **`parsers/record-jar.xslt`:**
262 Converts `text/record-jar` contents into a
263 `<html:div class="record-jar">` of `<html:dl>` elements (one for
264 each record).
265
266 - **`parsers/tsv.xslt`:**
267 Converts `text/tab-separated-values` contents into an
268 `<html:table class="tsv">` element.
269
270 New ⛩️📰 书社 parsers which target plaintext formats should have an
271 `<xslt:template>` element with no `@name` or `@mode` and whose
272 `@match` attribute…
273
274 - Starts with an appropriately‐namespaced qualified name for a
275 `<html:script>` element.
276
277 - Follows this with the string `[@type=`.
278
279 - Follows this with a quoted string giving a media type supported by
280 the parser.
281 Media type parameters are *not* supported.
282
283 - Follows this with the string `]`.
284
285 For example, the trivial `text/plain` parser is defined as follows :⁠—
286
287 ```xml
288 <?xml version="1.0"?>
289 <transform
290 xmlns="http://www.w3.org/1999/XSL/Transform"
291 xmlns:html="http://www.w3.org/1999/xhtml"
292 xmlns:书社="urn:fdc:ladys.computer:20231231:Shu1She4"
293 version="1.0"
294 >
295 <书社:id>example:text/plain</书社:id>
296 <template match="html:script[@type='text/plain']">
297 <html:pre><value-of select="."/></html:pre>
298 </template>
299 </transform>
300 ```
301
302 ⛩️📰 书社 will scan the provided parsers for this pattern to determine
303 the set of allowed plaintext file types.
304 Multiple such `<xslt:template>` elements may be provided in a single
305 parser, for example if the parser supports multiple media types.
306 Alternatively, you can set the `@书社:supported-media-types` attribute
307 on the root element of the parser to override media type support
308 detection.
309
310 Even when `@书社:supported-media-types` is set, it is a requirement
311 that each parser transform any `<html:script>` elements with a
312 `@type` which matches their registered types into something else.
313 Otherwise the parser will be stuck in an endless loop.
314 The result tree of applying the transform to the `<html:script>`
315 element will be reparsed (in case any new `<html:script>` elements
316 were added in its subtree), and a `@书社:parsed-by` attribute will be
317 added to each toplevel element in the result.
318 The value of this attribute will be the value of the `<书社:id>`
319 toplevel element in the parser.
320
321 It is possible for parsers to support zero plaintext types.
322 This is useful when targeting specific dialects of X·M·L; parsers in
323 this sense operate on the same basic principles as transforms
324 (described below).
325 The major distinction between X·M·L parsers and transforms is where in
326 the process the transformation happens:
327 Parsers are applied *prior* to embedding (and can be used to generate
328 embeds); transforms are applied *after*.
329
330 It is **strongly recommended** that auxillary templates in parsers be
331 namespaced (by `@name` or `@mode`) whenever possible, to avoid
332 conflicts between parsers.
333
334 ## Embedding
335
336 Documents can be embedded in other documents using a `<书社:link>`
337 element with `@xlink:show="embed"`.
338 The `@xlink:href`s of these elements should have the format
339 `about:shushe?source=<path>`, where `<path>` provides the path to the
340 file within `SRCDIR`.
341 Includes, which do not generate outputs of their own but may still be
342 freely embedded, instead use the format
343 `about:shushe?include=<path>`, where `<path>` provides the path
344 within `INCLUDEDIR`.
345
346 Embeds are replaced with the parsed contents of a file, unless the file
347 is an asset, in which case an `<html:object>` element is produced
348 instead (with the contents of the asset file provided as a base64
349 `data:` u·r·i).
350
351 Embedding takes place after parsing but before transformation, so
352 parsers are able to generate their own embeds.
353 ⛩️📰 书社 is able to detect the transitive embed dependencies of files
354 and update them accordingly; it will signal an error if the
355 dependencies are recursive.
356
357 ## Output Redirection
358
359 By default, ⛩️📰 书社 installs files to the same location in `DESTDIR`
360 as they were placed in their `SRCDIR`.
361 This behaviour can be customized by setting the `@书社:destination`
362 attribute on the root element, whose value can give a different path.
363 This attribute is read after parsing, but before transformation (where
364 it is silently dropped).
365
366 ## Transforms
367
368 Transforms are used to convert X·M·L files into their final output,
369 after all necessary parsing and embedding has taken place.
370 ⛩️📰 书社 comes with some transforms; namely :⁠—
371
372 - **`transforms/attributes.xslt`:**
373 Applies transforms to the children of any `<书社:apply-attributes>`
374 elements, and then applies the attributes of the
375 `<书社:apply-attributes>` to each result child, replacing the
376 element with the result.
377 This is useful in combination with image embeds to apply alt‐text to
378 the resulting `<html:img>`.
379
380 - **`transforms/asset.xslt`:**
381 Converts `<html:object>` elements which correspond to recognized
382 media types into the appropriate H·T·M·L elements, and deletes
383 `<html:style>` elements from the body of the document and moves
384 them to the head.
385
386 - **`transforms/metadata.xslt`:**
387 Provides basic `<html:head>` metadata.
388 This metadata is generated from `<html:meta>` elements with one of
389 the following `@itemprop` attributes :⁠—
390
391 - **`urn:fdc:ladys.computer:20231231:Shu1She4:title`:**
392 Provides the title of the page.
393
394 ⛩️📰 书社 automatically encapsulates embeds so that their metadata
395 does not propogate up to the embedding document.
396 To undo this behaviour, remove the `@itemscope` and `@itemtype`
397 attributes from the embed during the transformation phase.
398
399 The following are recommendations on effective creation of
400 transforms :⁠—
401
402 - Make template matchers as specific as possible.
403 It is likely an error if two transforms have templates which match
404 the same element (unless the templates have different priority).
405
406 - Namespace templates (with `@name` or `@mode`) whenever possible.
407
408 - Set `@exclude-result-prefixes` on the root `xslt:transform` element
409 to reduce the number of declared namespaces in the final result.
410
411 ## Global Params
412
413 The following params are made available globally in parsers and
414 transforms :⁠—
415
416 - **`BUILDTIME`:**
417 The current time.
418
419 - **`SRCREV`:**
420 The tag or hash of the current commit in the working directory (if
421 `GIT` is defined and `./.git` exists).
422
423 - **`SRCTIME`:**
424 The time at which the source file was last modified.
425
426 - **`VERSION`:**
427 The tag or hash of the current commit in `THISDIR` (if `GIT` is
428 defined and `$(THISDIR)/.git` exists).
429
430 The following params are only available in transforms :⁠—
431
432 - **`CATALOG`:**
433 The path of the catalog file (within `BUILDDIR`).
434
435 - **`PATH`:**
436 The path of the output file (within `DESTDIR`).
437
438 ## Output Wrapping
439
440 ⛩️📰 书社 will wrap the final output of the transforms in appropriate
441 `<html:html>` and `<html:body>` elements, so it is not necessary for
442 transforms to do this explicitly.
443 After performing the initial transform, ⛩️📰 书社 will match the root
444 node of the result in the following modes to fill in areas of the
445 wrapper :⁠—
446
447 - **`书社:header`:**
448 The result of matching in this mode is prepended into the
449 `<html:body>` of the output (before the transformation result).
450
451 - **`书社:footer`:**
452 The result of matching in this mode is appended into the
453 `<html:body>` of the output (after the transformation result).
454
455 - **`书社:metadata`:**
456 The result of matching in this mode is inserted into the
457 `<html:head>` of the output.
458
459 In addition to being called with the transform result, each of these
460 modes will additionally be called with a `<xslt:include>` element
461 corresponding to each transform.
462 If a transform has a `<书社:id>` top‐level element whose value is an
463 i·r·i, its `<xslt:include>` element will have a corresponding
464 `@书社:id` attribute.
465 This mechanism can be used to allow transforms to insert content
466 without matching any elements in the result; for example, the
467 following transform adds a link to a stylesheet to the `<html:head>`
468 of every page :⁠—
469
470 ```xml
471 <?xml version="1.0"?>
472 <transform
473 xmlns="http://www.w3.org/1999/XSL/Transform"
474 xmlns:html="http://www.w3.org/1999/xhtml"
475 xmlns:xslt="http://www.w3.org/1999/XSL/Transform"
476 xmlns:书社="urn:fdc:ladys.computer:20231231:Shu1She4"
477 exclude-result-prefixes="书社"
478 version="1.0"
479 >
480 <书社:id>example:add-stylesheet-links.xslt</书社:id>
481 <template match="xslt:include[@书社:id='example:add-stylesheet-links.xslt']" mode="书社:metadata">
482 <html:link rel="stylesheet" type="text/css" href="/style.css"/>
483 </template>
484 </transform>
485 ```
486
487 Output wrapping can be entirely disabled by adding a
488 `@书社:disable-output-wrapping` attribute to the top‐level element in
489 the result tree.
490
491 ## License
492
493 Source files are licensed under the terms of the <cite>Mozilla Public
494 License, version 2.0</cite>.
495 For more information, see [LICENSE](./LICENSE).
496
497 [draft-phillips-record-jar-01]: <https://datatracker.ietf.org/doc/html/draft-phillips-record-jar-01>
This page took 0.202427 seconds and 3 git commands to generate.