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