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