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