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