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