]> Lady’s Gitweb - Shushe/blob - README.markdown
Get rid of weird superfluous sed in i·d fallback
[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 - `cat`
95 - `cp`
96 - `date`
97 - `echo`
98 - `file`
99 - `find`
100 - `mkdir` (requires support for `-p`)
101 - `mv`
102 - `printf`
103 - `rm`
104 - `sed`
105 - `sleep`
106 - `stat`
107 - `test`
108 - `touch`
109 - `tr` (requires support for `-d`)
110 - `uuencode` (requires support for `-m` and `-r`)
111 - `xmlcatalog` (provided by `libxml2`)
112 - `xmllint` (provided by `libxml2`)
113 - `xsltproc` (provided by `libxslt`)
114
115 The following additional variables can be used to control the behaviour
116 of ⛩️📰 书社 :⁠—
117
118 - **`SRCDIR`:**
119 The location of the source files (default: `sources`).
120 Multiple source directories can be provided, so long as the same
121 file subpath doesn’t exist in more than one of them.
122
123 - **`INCLUDEDIR`:**
124 The location of source includes (default: `sources/includes`).
125 This can be inside of `SRCDIR`, but needn’t be.
126 Multiple include directories can be provided, so long as the same
127 file subpath doesn’t exist in more than one of them.
128
129 - **`BUILDDIR`:**
130 The location of the (temporary) build directory (default: `build`).
131 `make clean` will delete this, and it is recommended that it not be
132 used for programs aside from ⛩️📰 书社.
133
134 - **`DESTDIR`:**
135 The location of directory to output files to (default: `public`).
136 `make install` will overwrite files in this directory which
137 correspond to those in `SRCDIR`.
138 It *will not* touch other files, including those generated from files
139 in `SRCDIR` which have since been deleted.
140
141 Files are first compiled to `$(BUILDDIR)/public` before they are
142 copied to `DESTDIR`, so this folder is relatively quick and
143 inexpensive to re·create.
144 It’s reasonable to simply delete it before every `make install` to
145 ensure stale content is removed.
146
147 - **`THISDIR`:**
148 The location of the ⛩️📰 书社 `GNUmakefile`.
149 This should be set automatically when calling Make and shouldn’t ever
150 need to be set manually.
151 This variable is used to find the ⛩️📰 书社 `lib/` folder, which is
152 expected to be in the same location.
153
154 - **`MAGICDIR`:**
155 The location of the magic files to use (default: `$(THISDIR)/magic`).
156
157 - **`FINDOPTS`:**
158 Options to pass to `find` when searching for source files (default:
159 `-PE`).
160
161 - **`FINDRULES`:**
162 Rules to use with `find` when searching for source files (default:
163 `-flags -nohidden -and -not -name '.*'`).
164
165 - **`FINDINCLUDEOPTS`:**
166 Options to pass to `find` when searching for includes (default:
167 `$(FINDOPTS)`).
168
169 - **`FINDINCLUDERULES`:**
170 Rules to use with `find` when searching for includes (default:
171 `$(FINDRULES)`).
172
173 - **`PARSERS`:**
174 A white·space‐separated list of parsers to use (default:
175 `$(THISDIR)/parsers/*.xslt`).
176
177 - **`TRANSFORMS`:**
178 A white·space‐separated list of transforms to use (default:
179 `$(THISDIR)/transforms/*.xslt`).
180
181 - **`XMLTYPES`:**
182 A white·space‐separated list of media types to consider X·M·L
183 (default: `application/xml text/xml`).
184
185 - **`VERBOSE`:**
186 If this variable has a value, every recipe instruction will be
187 printed when it runs (default: empty).
188 This is helpful for debugging, but typically too noisy for general
189 usage.
190
191 ## Source Files
192
193 Source files may be placed in `SRCDIR` in any manner; the file
194 structure used there will match the output.
195 The type of source files is *not* determined by file extension, but
196 rather by magic number; this means that files **must** begin with
197 something recognizable.
198 Supported magic numbers include :⁠—
199
200 - `<?xml` for `application/xml` files
201 - `#!js` for `text/javascript` files
202 - `@charset "` for `text/css` files
203 - `#!tsv` for `text/tab-separated-values` files
204 - `%%` for `text/record-jar` files (unregistered; see
205 [[draft-phillips-record-jar-01][]])
206
207 Text formats with associated X·S·L·T parsers are wrapped in a H·T·M·L
208 `<script>` element whose `@type` gives its media type, and then
209 passed to the parser to process.
210 Source files whose media type does not have an associated X·S·L·T
211 parser are considered “assets” and will not be transformed.
212
213 For compatibility with this program, source filenames should not
214 contain Ascii whitespace or any of the following Ascii characters:
215 ``!"#$%&()-:<>?\^`{|}``.
216 These characters are either invalid in u·r·i’s or conflict with aspects
217 of the Make or commandline syntax.
218
219 ## Parsers
220
221 Parsers are used to convert plaintext files into X·M·L trees, as well
222 as convert plaintext formats which are already included inline in
223 existing source X·M·L documents.
224 ⛩️📰 书社 comes with some parsers; namely :⁠—
225
226 - **`parsers/plain.xslt`:**
227 Wraps `text/plain` contents in a `<html:pre class="plain">` element.
228
229 - **`parsers/record-jar.xslt`:**
230 Converts `text/record-jar` contents into a
231 `<html:div class="record-jar">` of `<html:dl>` elements (one for
232 each record).
233
234 - **`parsers/tsv.xslt`:**
235 Converts `text/tab-separated-values` contents into an
236 `<html:table class="tsv">` element.
237
238 New ⛩️📰 书社 parsers which target plaintext formats should have an
239 `<xslt:template>` element with no `@name` or `@mode` and whose
240 `@match` attribute…
241
242 - Starts with an appropriately‐namespaced qualified name for a
243 `<html:script>` element.
244
245 - Follows this with the string `[@type=`.
246
247 - Follows this with a quoted string giving a media type supported by
248 the parser.
249 Media type parameters are *not* supported.
250
251 - Follows this with the string `]`.
252
253 For example, the trivial `text/plain` parser is defined as follows :⁠—
254
255 ```xml
256 <?xml version="1.0"?>
257 <transform
258 xmlns="http://www.w3.org/1999/XSL/Transform"
259 xmlns:html="http://www.w3.org/1999/xhtml"
260 version="1.0"
261 >
262 <template match="html:script[@type='text/plain']">
263 <html:pre><value-of select="."/></html:pre>
264 </template>
265 </transform>
266 ```
267
268 ⛩️📰 书社 will scan the provided parsers for this pattern to determine
269 the set of allowed plaintext file types.
270 Multiple such `<xslt:template>` elements may be provided in a single
271 parser, for example if the parser supports multiple media types.
272 Alternatively, you can set the `@书社:supported-media-types` attribute
273 on the root element of the parser to override media type support
274 detection.
275
276 Parsers can also target specific dialects of X·M·L, in which case they
277 operate on the same basic principles as transforms (described below).
278 The major distinction between X·M·L parsers and transforms is where in
279 the process the transformation happens:
280 Parsers are applied *prior* to embedding (and can be used to generate
281 embeds); transforms are applied *after*.
282
283 It is **strongly recommended** that auxillary templates in parsers be
284 namespaced (by `@name` or `@mode`) whenever possible, to avoid
285 conflicts between parsers.
286
287 ## Embedding
288
289 Documents can be embedded in other documents using a `<书社:link>`
290 element with `@xlink:show="embed"`.
291 The `@xlink:href`s of these elements should have the format
292 `about:shushe?source=<path>`, where `<path>` provides the path to the
293 file within `SRCDIR`.
294 Includes, which do not generate outputs of their own but may still be
295 freely embedded, instead use the format
296 `about:shushe?include=<path>`, where `<path>` provides the path
297 within `INCLUDEDIR`.
298
299 Embeds are replaced with the parsed contents of a file, unless the file
300 is an asset, in which case an `<html:object>` element is produced
301 instead (with the contents of the asset file provided as a base64
302 `data:` u·r·i).
303
304 Embedding takes place after parsing but before transformation, so
305 parsers are able to generate their own embeds.
306 ⛩️📰 书社 is able to detect the transitive embed dependencies of files
307 and update them accordingly; it will signal an error if the
308 dependencies are recursive.
309
310 ## Transforms
311
312 Transforms are used to convert X·M·L files into their final output,
313 after all necessary parsing and embedding has taken place.
314 ⛩️📰 书社 comes with some transforms; namely :⁠—
315
316 - **`transforms/attributes.xslt`:**
317 Applies transforms to the children of any `<书社:apply-attributes>`
318 elements, and then applies the attributes of the
319 `<书社:apply-attributes>` to each result child, replacing the
320 element with the result.
321 This is useful in combination with image embeds to apply alt‐text to
322 the resulting `<html:img>`.
323
324 - **`transforms/asset.xslt`:**
325 Converts `<html:object>` elements which correspond to recognized
326 media types into the appropriate H·T·M·L elements, and deletes
327 `<html:style>` elements from the body of the document and moves
328 them to the head.
329
330 - **`transforms/metadata.xslt`:**
331 Provides basic `<html:head>` metadata.
332 This metadata is generated from `<html:meta>` elements with one of
333 the following `@itemprop` attributes :⁠—
334
335 - **`urn:fdc:ladys.computer:20231231:Shu1She4:title`:**
336 Provides the title of the page.
337
338 ⛩️📰 书社 automatically encapsulates embeds so that their metadata
339 does not propogate up to the embedding document.
340 To undo this behaviour, remove the `@itemscope` and `@itemtype`
341 attributes from the embed during the transformation phase.
342
343 The following are recommendations on effective creation of
344 transforms :⁠—
345
346 - Make template matchers as specific as possible.
347 It is likely an error if two transforms have templates which match
348 the same element (unless the templates have different priority).
349
350 - Namespace templates (with `@name` or `@mode`) whenever possible.
351
352 - Set `@exclude-result-prefixes` on the root `xslt:transform` element
353 to reduce the number of declared namespaces in the final result.
354
355 The params `$buildtime`, `$srctime`, and `$path` are available within
356 transforms and are initialized to the current time, the time that the
357 source file was last modified, and the path of the output file within
358 $(DESTDIR).
359
360 ## Output Wrapping
361
362 ⛩️📰 书社 will wrap the final output of the transforms in appropriate
363 `<html:html>` and `<html:body>` elements, so it is not necessary for
364 transforms to do this explicitly.
365 After performing the initial transform, ⛩️📰 书社 will match the root
366 node of the result in the following modes to fill in areas of the
367 wrapper :⁠—
368
369 - **`书社:header`:**
370 The result of matching in this mode is prepended into the
371 `<html:body>` of the output (before the transformation result).
372
373 - **`书社:footer`:**
374 The result of matching in this mode is appended into the
375 `<html:body>` of the output (after the transformation result).
376
377 - **`书社:metadata`:**
378 The result of matching in this mode is inserted into the
379 `<html:head>` of the output.
380
381 In addition to being called with the transform result, each of these
382 modes will additionally be called with a `<xslt:include>` element
383 corresponding to each transform.
384 If a transform has a `<书社:id>` top‐level element whose value is an
385 i·r·i, its `<xslt:include>` element will have a corresponding
386 `@书社:id` attribute.
387 This mechanism can be used to allow transforms to insert content
388 without matching any elements in the result; for example, the
389 following transform adds a link to a stylesheet to the `<html:head>`
390 of every page :⁠—
391
392 ```xml
393 <?xml version="1.0"?>
394 <transform
395 xmlns="http://www.w3.org/1999/XSL/Transform"
396 xmlns:html="http://www.w3.org/1999/xhtml"
397 xmlns:xslt="http://www.w3.org/1999/XSL/Transform"
398 xmlns:书社="urn:fdc:ladys.computer:20231231:Shu1She4"
399 exclude-result-prefixes="书社"
400 version="1.0"
401 >
402 <书社:id>example:add-stylesheet-links.xslt</书社:id>
403 <template match="xslt:include[@书社:id='example:add-stylesheet-links.xslt']" mode="书社:metadata">
404 <html:link rel="stylesheet" type="text/css" href="/style.css"/>
405 </template>
406 </transform>
407 ```
408
409 Output wrapping can be entirely disabled by adding a
410 `@书社:disable-output-wrapping` attribute to the top‐level element in
411 the result tree.
412
413 ## License
414
415 Source files are licensed under the terms of the <cite>Mozilla Public
416 License, version 2.0</cite>.
417 For more information, see [LICENSE](./LICENSE).
418
419 [draft-phillips-record-jar-01]: <https://datatracker.ietf.org/doc/html/draft-phillips-record-jar-01>
This page took 0.063614 seconds and 5 git commands to generate.