]> Lady’s Gitweb - Shushe/blob - README.markdown
Move expansion into its own transform
[Shushe] / README.markdown
1 <!--
2 SPDX-FileCopyrightText: 2024, 2025 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
26 † Assuming an operating system with a fairly featureful, and
27 Posix‐compliant, development setup (e·g, Macintosh ≥ version 10.8).
28 In fact, on Linux you will probably need to install a few programs:
29 `libxml2-utils`, `xsltproc`, `sharutils`, and `pax`.
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 ## Prerequisites
52
53 In most cases, ⛩📰 书社 aims to require only functionality which is
54 present in all Posix‐compliant (`POSIX.1-2001`) operating systems.
55 There are a few exceptions.
56 Details on particular programs are given below; if a program is not
57 listed, it is assumed that any Posix‐compliant implementation will
58 work.
59
60 ### `diff`
61
62 This is a Posix utility, but ⛩📰 书社 depends on functionality
63 introduced after `POSIX.1-2001` (the `-u` option, introduced in
64 `POSIX.1-2008`).
65 Macintosh systems somewhat interestingly implement this option
66 correctly in legacy mode (`COMMAND_MODE=legacy`) but incorrectly by
67 default (despite claiming `POSIX.1-2008` conformance for this
68 utility).
69 [Note this erroneous comment claiming nanosecond & timezone are
70 extensions rather than standardized.][rdar-92753335]
71 Despite this, the default Macintosh implementation will still work with
72 ⛩📰 书社, with the caveat that the timestamp will only include a
73 fractional component when a Posix⹀compliant (e·g, Macintosh legacy or
74 G·N·U) implementation is used.
75
76 ### `file`
77
78 This is a Posix utility, but it was considered optional in
79 `POSIX.1-2001` (altho it was made mandatory in `POSIX.1-2008`) and
80 ⛩📰 书社 currently depends on unspecified behaviour.
81 It requires support for the following additional options :⁠—
82
83 - **`-C`**, when supplied with `-m`, must be useable to compile a
84 `.mgc` magicfile for use with future invocations of `file`.
85
86 - **`--files-from`** must be useable to provide a file that `file`
87 should read file·names from, and `-` must be useable in this
88 context to specify the standard input.
89
90 - **`--mime-type`** must cause `file` to print the internet media type
91 of the file with no charset parameter.
92
93 - **`--separator`** must be useable to set the separator that `file`
94 uses to separate file names from types.
95
96 These options are implemented by the
97 [Fine Free File Command](https://darwinsys.com/file/), which is used
98 by most operating systems.
99
100 ### `git`
101
102 This is not a Posix utility.
103 Usage of `git` is optional, but recommended (and activated by default).
104 To disable it, set `GIT=`.
105
106 ### `make`
107
108 This is a Posix utility, but it is considered an optional Software
109 Development utility and ⛩📰 书社 currently depends on unspecified
110 behaviour.
111 ⛩📰 书社 requires specifically the G·N·U version of `make`, and
112 depends on functionality present in version 3.81 or later.
113 It is not expected to work in previous versions, or with other
114 implementations of Make.
115
116 ### `pax`
117
118 This is a Posix utility, but it is not included in the Linux Standard
119 Base or installed by default in many distributions.
120 ⛩📰 书社 only requires support for the `ustar` format.
121
122 ### `uudecode` and `uuencode`
123
124 These are Posix utilities, but they were considered optional in
125 `POSIX.1-2001` (altho they are made mandatory in `POSIX.1-2008`) and
126 they are not included in the Linux Standard Base or installed by
127 default in many distributions.
128 The G·N·U [Sharutils](https://www.gnu.org/software/sharutils/) package
129 provides one implementation.
130
131 ### `xmlcatalog` and `xmllint`
132
133 These are not a Posix utilities.
134 They are a part of `libxml2`, but may need to be installed separately
135 on some platforms (e·g by the name `libxml2-utils`).
136
137 ### `xsltproc`
138
139 This is not a Posix utility.
140 It is a part of `libxslt`, but may need to be installed separately on
141 some platforms.
142
143 ## Basic Usage
144
145 Place source files in `sources/` and run `make install` to compile
146 the result to `public/`.
147 Compilation involves the following steps :⁠—
148
149 1. ⛩📰 书社 compiles all of the magic files in `magic/` into a single
150 file, `build/magic.mgc`.
151
152 2. ⛩📰 书社 processes all of the parsers in `parsers/` and determines
153 the list of supported plaintext types.
154
155 3. ⛩📰 书社 identifies all of the source files and includes and uses
156 `build/magic.mgc` to classify them by media type.
157
158 4. ⛩📰 书社 parses all plaintext and X·M·L source files and includes
159 and then builds a dependency tree between them.
160
161 5. ⛩📰 书社 uses the dependency tree to establish prerequisites for
162 each output file.
163
164 6. ⛩📰 书社 compiles each output file to `build/result`.
165
166 7. ⛩📰 书社 copies most output files from `build/result` to
167 `build/public`, but it does some additional processing instead on
168 those which indicate a non‐X·M·L desired final output form.
169
170 8. ⛩📰 书社 copies the final resulting files to `public`.
171
172 You can use `make list` to list each identified source file or include
173 alongside its computed type and dependencies.
174 As this is a Make‐based program, steps will only be run if the
175 corresponding buildfile or output file is older than its
176 prerequisites.
177
178 ## Name·spaces
179
180 The ⛩📰 书社 name·space is `urn:fdc:ladys.computer:20231231:Shu1She4`.
181
182 This document uses a few name·space prefixes, with the following
183 meanings :⁠—
184
185 | Prefix | Expansion |
186 | ---------: | :-------------------------------------------- |
187 | `catalog:` | `urn:oasis:names:tc:entity:xmlns:xml:catalog` |
188 | `exsl:` | `http://exslt.org/common` |
189 | `exslstr:` | `http://exslt.org/strings` |
190 | `html:` | `http://www.w3.org/1999/xhtml` |
191 | `rdf:` | `http://www.w3.org/1999/02/22-rdf-syntax-ns#` |
192 | `svg:` | `http://www.w3.org/2000/svg` |
193 | `xlink:` | `http://www.w3.org/1999/xlink` |
194 | `xslt:` | `http://www.w3.org/1999/XSL/Transform` |
195 | `书社:` | `urn:fdc:ladys.computer:20231231:Shu1She4` |
196
197 ## Setup and Configuration
198
199 ⛩📰 书社 depends on the following programs to run.
200 In every case, you may supply your own implementation by overriding the
201 corresponding (allcaps) variable (e·g, set `MKDIR` to supply your own
202 `mkdir` implementation).
203
204 - `awk`
205 - `cat`
206 - `cd`
207 - `cksum`
208 - `cp`
209 - `date`
210 - `diff`
211 - `file`
212 - `find`
213 - `git` (optional; set `GIT=` to disable)
214 - `grep`
215 - `ln`
216 - `mkdir`
217 - `mv`
218 - `od`
219 - `pax` (only when generating archives)
220 - `printf`
221 - `rm`
222 - `sed`
223 - `sleep`
224 - `test`
225 - `touch`
226 - `tr`
227 - `uuencode`
228 - `uudecode`
229 - `xargs`
230 - `xmlcatalog` (provided by `libxml2`)
231 - `xmllint` (provided by `libxml2`)
232 - `xsltproc` (provided by `libxslt`)
233
234 The following additional variables can be used to control the behaviour
235 of ⛩📰 书社 :⁠—
236
237 - **`SRCDIR`:**
238 The location of the source files (default: `sources`).
239 Multiple source directories can be provided, so long as the same
240 file subpath doesn’t exist in more than one of them.
241
242 - **`INCLUDEDIR`:**
243 The location of source includes (default: `sources/includes`).
244 This can be inside of `SRCDIR`, but needn’t be.
245 Multiple include directories can be provided, so long as the same
246 file subpath doesn’t exist in more than one of them.
247
248 - **`DATADIR`:**
249 If set to the location of a directory, ⛩📰 书社 will run a two‐stage build.
250 In the first stage, only files in `SRCDIR` which match `FINDDATARULES` (see below) will be built, with files in `DATADIR` serving as includes.
251 In the second stage, the remaining files in `SRCDIR` will be built, with the files built during the first stage, in addition to any files in `INCLUDEDIR`, serving as includes.
252 Files built during the first stage are copied into `DESTDIR` alongside those from the second stage when installing.
253
254 This functionality is intended for sites where the bulk of the site can be built from a few data files which are expensive to create.
255
256 - **`BUILDDIR`:**
257 The location of the (temporary) build directory (default: `build`).
258 `make clean` will delete this, and it is recommended that it not be
259 used for programs aside from ⛩📰 书社.
260
261 - **`DESTDIR`:**
262 The location of directory to output files to (default: `public`).
263 `make install` will overwrite files in this directory which
264 correspond to those in `SRCDIR`.
265 It *will not* touch other files, including those generated from files
266 in `SRCDIR` which have since been deleted.
267
268 Files are first compiled to `$(BUILDDIR)/public` before they are
269 copied to `DESTDIR`, so this folder is relatively quick and
270 inexpensive to re·create.
271 It’s reasonable to simply delete it before every `make install` to
272 ensure stale content is removed.
273
274 - **`THISDIR`:**
275 The location of the ⛩📰 书社 `GNUmakefile`.
276 This should be set automatically when calling Make and shouldn’t ever
277 need to be set manually.
278 This variable is used to find the ⛩📰 书社 `lib/` folder, which is
279 expected to be in the same location.
280
281 - **`MAGIC`:**
282 A white·space‐separated list of magic files to use (default:
283 `$(THISDIR)/magic/*`).
284
285 - **`EXTRAMAGIC`:**
286 The value of this variable is appended to `MAGIC` by default, to
287 enable additional magic files without overriding the existing ones.
288
289 - **`FINDRULES`:**
290 Rules to use with `find` when searching for source files.
291 The default ignores files that start with a period or hyphen‐minus,
292 those which end with a cloparen, and those which contain a hash,
293 buck, percent, asterisk, colon, semi, eroteme, bracket, backslash,
294 or pipe.
295 It is important that these rules not produce any output, as anything
296 printed to `stdout` will be considered a result of the find.
297
298 - **`EXTRAFINDRULES`:**
299 The value of this variable is appended to `FINDRULES` by default, to
300 enable additional rules without overriding the existing ones.
301
302 - **`FINDINCLUDERULES`:**
303 Rules to use with `find` when searching for includes (default:
304 `$(FINDRULES)`).
305
306 - **`EXTRAFINDINCLUDERULES`:**
307 The value of this variable is appended to `FINDINCLUDERULES` by
308 default, to enable additional rules without overriding the existing
309 ones.
310
311 - **`DATAOPTS`:**
312 Additional options to use when calling Make during the first stage of a two‐stage build using `DATADIR`.
313
314 This can be used to override variables which are only applicable during the second stage.
315 Note that when supplying this variable on the shell, it will need to be double‐quoted.
316
317 - **`DATAEXT`:**
318 A list of file extensions which signify “data” files during a two‐stage build using `DATADIR`.
319
320 - **`FINDDATARULES`:**
321 Rules to use with `find` when searching for data files.
322 By default, these rules are derived from `DATAEXT`.
323
324 - **`EXTRAFINDDATARULES`:**
325 The value of this variable is appended to `FINDDATARULES` by
326 default, to enable additional rules without overriding the existing
327 ones.
328
329 - **`FINDFILTERONLY`:**
330 A semicolon‐separated list of regular expressions, at least one of which the paths for sources and includes are required to match, unless empty (default: empty).
331
332 - **`FINDFILTEROUT`:**
333 A semicolon‐separated list of regular expressions, each of which matches paths that should _not_ be considered sources or includes (default: empty).
334
335 - **`FINDINCLUDEFILTERONLY`:**
336 A semicolon‐separated list of regular expressions, at least one of which the paths for includes are required to match, unless empty (default: empty).
337
338 Note that only paths which already match `FINDFILTERONLY` are considered.
339
340 - **`FINDINCLUDEFILTEROUT`:**
341 A semicolon‐separated list of regular expressions, each of which matches paths that should _not_ be considered includes, but may still be considered sources (default: empty).
342
343 - **`FINDFILTERONLYEXTENDED`:**
344 If non·empty, `FINDFILTERONLY` is an extended regular expression; otherwise, it is basic (default: empty).
345
346 - **`FINDFILTEROUTEXTENDED`:**
347 If non·empty, `FINDFILTEROUT` is an extended regular expression; otherwise, it is basic (default: matches `FINDFILTERONLYEXTENDED`).
348
349 - **`FINDINCLUDEFILTERONLYEXTENDED`:**
350 If non·empty, `FINDINCLUDEFILTERONLY` is an extended regular expression; otherwise, it is basic (default: matches `FINDFILTERONLYEXTENDED`).
351
352 - **`FINDINCLUDEFILTEROUTEXTENDED`:**
353 If non·empty, `FINDINCLUDEFILTEROUT` is an extended regular expression; otherwise, it is basic (default: `1` if either `FINDFILTEROUTEXTENDED` or `FINDINCLUDEFILTERONLYEXTENDED` is non·empty).
354
355 - **`PARSERS`:**
356 A white·space‐separated list of parsers to use (default:
357 `$(THISDIR)/parsers/*.xslt`).
358
359 - **`EXTRAPARSERS`:**
360 The value of this variable is appended to `PARSERS` by default, to
361 enable additional parsers without overriding the existing ones.
362
363 - **`PARSERLIBS`:**
364 A white·space‐separated list of parser dependencies (default:
365 `$(THISDIR)/lib/split.xslt`).
366
367 - **`EXTRAPARSERLIBS`:**
368 The value of this variable is appended to `PARSERLIBS` by default, to
369 enable additional parser dependencies without overriding the
370 existing ones.
371
372 - **`TRANSFORMS`:**
373 A white·space‐separated list of transforms to use (default:
374 `$(THISDIR)/transforms/*.xslt`).
375
376 - **`EXTRATRANSFORMS`:**
377 The value of this variable is appended to `TRANSFORMS` by default, to
378 enable additional transforms without overriding the existing ones.
379
380 - **`TRANSFORMLIBS`:**
381 A white·space‐separated list of transform dependencies (default:
382 `$(THISDIR)/lib/serialize.xslt`).
383
384 - **`EXTRATRANSFORMLIBS`:**
385 The value of this variable is appended to `TRANSFORMLIBS` by default,
386 to enable additional transform dependencies without overriding the
387 existing ones.
388
389 - **`XMLTYPES`:**
390 A white·space‐separated list of media types or media type suffixes to
391 consider X·M·L (default: `application/xml text/xml +xml`).
392
393 - **`FINALIZE`:**
394 A program to run on (unspecial) X·M·L files after they are
395 transformed (default: `xmllint --nonet --nsclean`).
396 This variable can be used for postprocessing.
397
398 - **`THISREV`:**
399 The current version of ⛩📰 书社 (default: derived from the current
400 git tag/branch/commit).
401
402 - **`SRCREV`:**
403 The current version of the source files (default: derived from the
404 current git tag/branch/commit).
405
406 - **`QUIET`:**
407 If this variable has a value, informative messages will not be
408 printed (default: empty).
409 Informative messages print to stderr, not stdout, so disabling them
410 usually shouldn’t be necessary.
411 This does not (cannot) disable messages from Make itself, for which
412 the `-s`, `--silent` ∕ `--quiet` Make option is more likely to be
413 useful.
414
415 - **`VERBOSE`:**
416 If this variable has a value, every recipe instruction will be
417 printed when it runs (default: empty).
418 This is helpful for debugging, but typically too noisy for general
419 usage.
420
421 ## Source Files
422
423 Source files may be placed in `SRCDIR` in any manner; the file
424 structure used there will match the output.
425 The type of source files is *not* determined by file extension, but
426 rather by magic number; this means that files **must** begin with
427 something recognizable.
428 Supported magic numbers include :⁠—
429
430 - `<?xml` for `application/xml` files
431 - `#!js` for `text/javascript` files
432 - `@charset "` for `text/css` files
433 - `#!tsv` for `text/tab-separated-values` files
434 - `%%` for `text/record-jar` files (unregistered; see
435 [[draft-phillips-record-jar-01][]])
436
437 Text formats with associated X·S·L·T parsers are wrapped in a H·T·M·L
438 `<script>` element whose `@type` gives its media type, and then
439 passed to the parser to process.
440 Source files whose media type does not have an associated X·S·L·T
441 parser are considered “assets” and will not be transformed.
442
443 **☡ For compatibility with this program, source file·names must not
444 contain Ascii white·space, colons (`:`), semis (`;`), pipes (`|`),
445 bucks (`$`), percents (`%`), hashes (`#`), asterisks (`*`), brackets
446 (`[` or `]`), erotemes (`?`), backslashes (`\`), or control
447 characters, must not begin with a hyphen‐minus (`-`), and must not end
448 with a cloparen (`)`).**
449 The former characters have the potential to conflict with make syntax,
450 a leading hyphen‐minus is confusable for a commandline argument, and a
451 trailing cloparen [activates a bug in G·N·U Make
452 3.81](https://stackoverflow.com/questions/17148468/capturing-filenames-including-parentheses-with-gnu-makes-wildcard-function#comment24825307_17148894).
453
454 ## Parsers
455
456 Parsers are used to convert plaintext files into X·M·L trees, as well
457 as convert plaintext formats which are already included inline in
458 existing source X·M·L documents.
459 ⛩📰 书社 comes with some parsers; namely :⁠—
460
461 - **`parsers/plain.xslt`:**
462 Wraps `text/plain` contents in a `<html:pre>` element.
463
464 - **`parsers/record-jar.xslt`:**
465 Converts `text/record-jar` contents into a `<html:div>` of
466 `<html:dl>` elements (one for each record).
467
468 - **`parsers/tsv.xslt`:**
469 Converts `text/tab-separated-values` contents into an `<html:table>`
470 element.
471
472 New ⛩📰 书社 parsers which target plaintext formats should have an
473 `<xslt:template>` element with no `@name` or `@mode` and whose
474 `@match` attribute…
475
476 - Starts with an appropriately‐name·spaced qualified name for a
477 `<html:script>` element.
478
479 - Follows this with the string `[@type=`.
480
481 - Follows this with a quoted string giving a media type supported by
482 the parser.
483 Media type parameters are *not* supported.
484
485 - Follows this with the string `]`.
486
487 For example, the trivial `text/plain` parser is defined as follows :⁠—
488
489 ```xml
490 <?xml version="1.0"?>
491 <transform
492 xmlns="http://www.w3.org/1999/XSL/Transform"
493 xmlns:html="http://www.w3.org/1999/xhtml"
494 xmlns:书社="urn:fdc:ladys.computer:20231231:Shu1She4"
495 version="1.0"
496 >
497 <书社:id>example:text/plain</书社:id>
498 <template match="html:script[@type='text/plain']">
499 <html:pre><value-of select="."/></html:pre>
500 </template>
501 </transform>
502 ```
503
504 ⛩📰 书社 will scan the provided parsers for this pattern to determine
505 the set of allowed plaintext file types.
506 Multiple such `<xslt:template>` elements may be provided in a single
507 parser, for example if the parser supports multiple media types.
508 Alternatively, you can set the `@书社:supported-media-types` attribute
509 on the root element of the parser to override media type support
510 detection.
511
512 Even when `@书社:supported-media-types` is set, it is a requirement
513 that each parser transform any `<html:script>` elements with a
514 `@type` which matches their registered types into something else.
515 Otherwise the parser will be stuck in an endless loop.
516 The result tree of applying the transform to the `<html:script>`
517 element will be reparsed (in case any new `<html:script>` elements
518 were added in its subtree), and a `@书社:parsed-by` attribute will be
519 added to each toplevel element in the result.
520 The value of this attribute will be the value of the `<书社:id>`
521 toplevel element in the parser.
522
523 It is possible for parsers to support zero plaintext types.
524 This is useful when targeting specific dialects of X·M·L; parsers in
525 this sense operate on the same basic principles as transforms
526 (described below).
527 The major distinction between X·M·L parsers and transforms is where in
528 the process the transformation happens:
529 Parsers are applied *prior* to embedding (and can be used to generate
530 embeds); transforms are applied *after*.
531
532 It is **strongly recommended** that auxillary templates in parsers be
533 name·spaced (by `@name` or `@mode`) whenever possible, to avoid
534 conflicts between parsers.
535
536 ### Attributes added during parsing
537
538 ⛩📰 书社 will add a few attributes to elements which result from
539 parsing plaintext `<html:script>` elements.
540 These include :⁠—
541
542 - A `@书社:parsed-by` attribute, giving a space‐separated list of
543 parsers which parsed the node.
544 (Generally, this will be a list of one, but it is possible for the
545 result of a parse to be another plaintext node, which may be parsed
546 by a different parser.)
547
548 - A `@书社:media-type` attribute, giving the identified media type of
549 the plaintext node.
550
551 ### Parsed metadata
552
553 It is possible to extract metadata from a document at the same time as
554 it is being parsed.
555 This is done by creating result elements in the `书社:about` mode;
556 these should be R·D·F property elements which apply to the conceptual
557 entity that is the document being parsed.
558
559 During transformation, metadata for the file with identifier `$FILE`
560 can be read from the children of
561 `$书社:about//*[@rdf:about=$FILE]/nie:interpretedAs/*`.
562
563 ## Output Redirection
564
565 By default, ⛩📰 书社 installs files to the same location in `DESTDIR`
566 as they were placed in their `SRCDIR`.
567 This behaviour can be customized by setting the `@书社:destination`
568 attribute on the root element, whose value can give a different path.
569 This attribute is read after parsing, but before transformation (where
570 it is silently dropped).
571
572 ## Embedding
573
574 Documents can be embedded in other documents using a `<书社:link>`
575 element with `@xlink:show="embed"`.
576 The `@xlink:href`s of these elements should have the format
577 `about:shushe?source=<path>`, where `<path>` provides the path to the
578 file within `SRCDIR`.
579 Includes, which do not generate outputs of their own but may still be
580 freely embedded, instead use the format
581 `about:shushe?include=<path>`, where `<path>` provides the path
582 within `INCLUDEDIR`.
583
584 Embeds are replaced with the parsed contents of a file, unless the file
585 is an asset, in which case an `<html:object>` element is produced
586 instead (with the contents of the asset file provided as a base64
587 `data:` u·r·i).
588 Embed replacements will be given a `@书社:identifier` attribute whose
589 value will match the `@xlink:href` of the embed.
590
591 Embedding takes place after parsing but before transformation, so
592 parsers are able to generate their own embeds.
593 ⛩📰 书社 is able to detect the transitive embed dependencies of files
594 and update them accordingly; it will signal an error if the
595 dependencies are recursive.
596
597 ### Attributes added during expansion
598
599 ⛩📰 书社 will add a few attributes to toplevel result elements, both
600 in the main document and any embedded documents, during the expansion
601 phase prior to the main transformation.
602 These include :⁠—
603
604 - A `@书社:cksum` attribute giving the `cksum` checksum of the
605 corresponding source file.
606
607 - A `@书社:mtime` attribute giving the last modified time of the
608 corresponding source file.
609
610 - A `@书社:identifier` attribute giving the ⛩📰 书社 identifier
611 (i·e, starting with `about:shushe?`) of the corresponding source
612 file.
613
614 - For elements in the `html` namespace, an `itemscope` attribute and an
615 `itemtype` attribute with a value of
616 `urn:fdc:ladys.computer:20231231:Shu1She4:document` (for the main
617 document) or `urn:fdc:ladys.computer:20231231:Shu1She4:embed` (for
618 embedded documents).
619 These attributes are used to scope any nested `<html:meta>` elements
620 with `@itemprop` attributes to their containing documents.
621
622 ## Transforms
623
624 Transforms are used to convert X·M·L files into their final output,
625 after all necessary parsing and embedding has taken place.
626 ⛩📰 书社 comes with some transforms; namely :⁠—
627
628 - **`transforms/asset.xslt`:**
629 Converts `<html:object>` elements which correspond to recognized
630 media types into the appropriate H·T·M·L elements, and deletes
631 `<html:style>` elements from the body of the document and moves
632 them to the head.
633 This conversion happens during the finalization phase, after the main
634 transformation.
635
636 - **`transforms/expansion.xslt`:**
637 Performs embedding, as described above.
638
639 - **`transforms/metadata.xslt`:**
640 Provides basic `<html:head>` metadata.
641 This metadata is generated from `<html:meta>` elements with one of
642 the following `@itemprop` attributes :⁠—
643
644 - **`urn:fdc:ladys.computer:20231231:Shu1She4:title`:**
645 Provides the title of the page.
646
647 ⛩📰 书社 automatically encapsulates H·T·M·L embeds so that their
648 metadata does not propogate up to the embedding document.
649 To undo this behaviour, remove the `@itemscope` and `@itemtype`
650 attributes from the embed during the transformation phase.
651
652 - **`transforms/serialization.xslt`:**
653 Replaces `<书社:serialize-xml>` elements with the (escaped)
654 serialized X·M·L of their contents.
655 This replacement happens during the finalization phase, after most
656 other transformations have taken place.
657
658 If a `@with-namespaces` attribute is provided, any name·space nodes
659 on the toplevel serialized elements whose U·R·I’s correspond to the
660 definitions of the provided prefixes, as defined for the
661 `<书社:serialize-xml>` element, will be declared using name·space
662 attributes on the serialized elements.
663 Otherwise, only name·space nodes which _differ_ from the definitions
664 on the `<书社:serialize-xml>` element will be declared.
665 The string `#default` may be used to represent the default
666 name·space.
667 Multiple prefixes may be provided, separated by white·space.
668
669 When it comes to name·spaces used internally by ⛩📰 书社, the
670 prefix used by ⛩📰 书社 may be declared _in addition to_ the
671 prefix(es) used in the source document(s).
672 It is not possible to selectively only declare one prefix for a
673 name·space to the exclusion of others.
674
675 `<书社:raw-output>` elements may be used inside of
676 `<书社:serialize-xml>` elements to inject raw output into the
677 serialized X·M·L.
678
679 The following are recommendations on effective creation of
680 transforms :⁠—
681
682 - Make template matchers as specific as possible.
683 It is likely an error if two transforms have templates which match
684 the same element (unless the templates have different priority).
685
686 - Name·space templates (with `@name` or `@mode`) whenever possible.
687
688 - Set `@exclude-result-prefixes` on the root `xslt:transform` element
689 to reduce the number of declared name·spaces in the final result.
690
691 ## Global Params
692
693 The following params are made available globally in parsers and
694 transforms :⁠—
695
696 - **`BUILDTIME`:**
697 The current time.
698
699 - **`IDENTIFIER`:**
700 The ⛩📰 书社 identifier of the source file (a u·r·i beginning with
701 `about:shushe`).
702
703 - **`SRCREV`:**
704 The value of the `SRCREV` variable (if present).
705
706 - **`THISREV`:**
707 The value of the `THISREV` variable (if present).
708
709 In transforms, the following params are additionally available :⁠—
710
711 - **`书社:about`:**
712 R·D·F metadata about all of the documents ⛩📰 书社 knows about.
713 Use `$书社:about//*[@rdf:about=$IDENTIFIER]` to get the metadata for
714 the current document.
715
716 - **`书社:source`:**
717 The parsed source document being transformed, prior to any expansion.
718
719 - **`书社:expansion`:**
720 The document after the all embeds have been expanded.
721 Unavailable during the `书社:expand` stage.
722
723 - **`书社:result`:**
724 The document after the main set of transformations have been applied.
725 Only available during the `书社:finalize` stage, where it is used to
726 apply output wrapping and other clean·up.
727
728 ## Output Wrapping
729
730 Provided at least one toplevel result element belongs to the H·T·M·L
731 namespace, ⛩📰 书社 will wrap the final output of the transforms in
732 appropriate `<html:html>` and `<html:body>` elements, so it is not
733 necessary for transforms to do this explicitly.
734 If a toplevel result element _is_ a `<html:html>` and `<html:body>`
735 element, it will be merged with the one that ⛩📰 书社 creates.
736 Consequently, wrapping the result in a `<html:body>` element can be
737 used to enable wrapping for non‐H·T·M·L content, when desired.
738
739 As a part of this process, after performing the initial transform
740 ⛩📰 书社 will match in the following modes to fill in areas of the
741 wrapper :⁠—
742
743 - **`书社:header`:**
744 The result of matching in this mode is prepended into the
745 `<html:body>` of the output (before the transformation result).
746
747 - **`书社:footer`:**
748 The result of matching in this mode is appended into the
749 `<html:body>` of the output (after the transformation result).
750
751 - **`书社:metadata`:**
752 The result of matching in this mode is inserted into the
753 `<html:head>` of the output.
754
755 The document being matched will contain the full transform result
756 prior to wrapping as well as an `<书社:id>` element for each
757 transform.
758 The latter elements can be matched to enable transforms to provide
759 content _without_ matching any elements in the result; for example,
760 the following transform adds a link to a stylesheet to the
761 `<html:head>` of every page :⁠—
762
763 ```xml
764 <?xml version="1.0"?>
765 <transform
766 xmlns="http://www.w3.org/1999/XSL/Transform"
767 xmlns:html="http://www.w3.org/1999/xhtml"
768 xmlns:xslt="http://www.w3.org/1999/XSL/Transform"
769 xmlns:书社="urn:fdc:ladys.computer:20231231:Shu1She4"
770 exclude-result-prefixes="书社"
771 version="1.0"
772 >
773 <书社:id>example:add-stylesheet-links.xslt</书社:id>
774 <template match="书社:id[string(.)='example:add-stylesheet-links.xslt']" mode="书社:metadata">
775 <html:link rel="stylesheet" type="text/css" href="/style.css"/>
776 </template>
777 </transform>
778 ```
779
780 Output wrapping can be entirely disabled by adding a
781 `@书社:disable-output-wrapping` attribute to the top‐level element in
782 the result tree.
783 It will not be performed on outputs whose root elements are
784 `<书社:archive>`, `<书社:base64-binary>`, or `<书社:raw-text>`
785 (described below), or on result trees which do not contain a toplevel
786 element in the H·T·M·L namespace.
787
788 ## Applying Attributes
789
790 The `<书社:apply-attributes>` element will apply any attributes on the
791 element to the element(s) it wraps.
792 It is especially useful in combination with embeds.
793
794 The `<书社:apply-attributes-to-root>` element will apply any attributes
795 on the element to the root node of the final transformation result.
796 It is especially useful in combination with output wrapping.
797
798 In both cases, attributes from various sources are combined with
799 white·space between them.
800 Attribute application takes place after each stage of the
801 transformation, including after the initial embedding phase.
802
803 Both elements ignore attributes in the `xml:` name·space, except for
804 `@xml:lang`, which ignores all but the first definition (including
805 any already present on the root element).
806 On H·T·M·L and S·V·G elements, `@lang` has the same behaviour as
807 `@xml:lang`.
808
809 ## Other Kinds of Output
810
811 There are a few special elements in the `书社:` name·space which, if
812 they appear as the toplevel element in a transformation result, cause
813 ⛩📰 书社 to produce something other than an X·M·L file.
814 They are :⁠—
815
816 - **`<书社:archive>`:**
817 Each child element with a `@书社:archived-as` attribute will be
818 archived as a separate file in a resulting tarball (this attribute
819 gives the file name).
820 These elements will be processed the same as the root elements of any
821 other file (e·g, they will be wrapped; they can themselves specify
822 non X·M·L output types, ⁊·c).
823 Other child elements will be ignored.
824
825 If the `<书社:archive>` element is given an `@书社:expanded`
826 attribute, rather than producing a tarball ⛩📰 书社 will output
827 the directory which expanding the tarball would produce.
828 This mechanism can be used to generate multiple files from a single
829 source, provided all of the files are contained with·in the same
830 directory.
831
832 - **`<书社:base64-binary>`:**
833 The text nodes in the transformation result will, after removing all
834 Ascii whitespace, be treated as a Base·64 string, which is then
835 decoded.
836
837 - **`<书社:raw-text>`:**
838 A plaintext (U·T·F‐8) file will be produced from the text nodes in
839 the transformation result.
840
841 ## License
842
843 This repository conforms to [REUSE][].
844
845 Most source files are licensed under the terms of the <cite>Mozilla
846 Public License, version 2.0</cite>.
847
848 [REUSE]: <https://reuse.software/spec/>
849 [draft-phillips-record-jar-01]: <https://datatracker.ietf.org/doc/html/draft-phillips-record-jar-01>
850 [rdar-92753335]: <https://github.com/apple-oss-distributions/patch_cmds/blob/5084833f90df1b0e0924ea56f94c0199b3b8bbc6/diff/diffreg.c#L1800-L1808>
This page took 0.123967 seconds and 5 git commands to generate.