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