# ⛩️📰 书社 A make·file for X·M·L. ⛩️📰 书社 aims to make it easy to generate websites with X·S·L·T and G·N·U Make. It is consequently only a good choice for people who like X·S·L·T and G·N·U Make and wish it were easier to make websites with them. It makes things easier by :⁠— - Automatically identifying source files and characterizing them by type (X·M·L, text, or asset). - Parsing supported text types into X·M·L trees. - Enabling easy inclusion of source files within each other. It aims to do this with zero dependencies beyond the programs already installed on your computer. (On Linux machines, you may need to install `libxml2-utils` to get the commandline programs from `libxml2`.) **Note:** ⛩️📰 书社 requires functionality present in G·N·U Make 3.81 (or later) and will not work in previous versions, or other implementations of Make. Compatibility with later versions of G·N·U Make is assumed, but not tested. ## Nomenclature 书社 is a Chinese word meaning “publishing house”. The first character, 书, is the simplified form of “document”. The second character, 社, contemporarily means “association”, but historically referred to the god of the soil and related altars or festivities. In Japanese, it is an alternate spelling for やしろ, the word for “Shinto shrine”. The name 书社 was chosen to play on this pun, as it is intended as a publishing program for webshrines. In Ascii environments, ⛩️📰 书社 should be written `Shushe`, following the pinyin transliteration. ## Basic Usage Place source files in `sources/` and run `make install` to compile the result to `public/`. Compilation involves the following steps :⁠— 1. ⛩️📰 书社 compiles all of the magic files in `magic/` into a single file, `build/magic.mgc`. 2. ⛩️📰 书社 processes all of the parsers in `parsers/` and determines the list of supported plaintext types. 3. ⛩️📰 书社 identifies all of the source files and includes and uses `build/magic.mgc` to classify them by media type. 4. ⛩️📰 书社 parses all plaintext and X·M·L source files and includes and then builds a dependency tree between them. 5. ⛩️📰 书社 uses the dependency tree to establish prerequisites for each output file. 6. ⛩️📰 书社 compiles each output file to `build/result`. 7. ⛩️📰 书社 copies most output files from `build/result` to `build/public`, but it does some additional processing instead on those which indicate a non‐X·M·L desired final output form. 8. ⛩️📰 书社 copies the final resulting files to `public`. You can use `make list` to list each identified source file or include alongside its computed type and dependencies. As this is a Make‐based program, steps will only be run if the corresponding buildfile or output file is older than its prerequisites. ## Name·spaces The ⛩️📰 书社 name·space is `urn:fdc:ladys.computer:20231231:Shu1She4`. This document uses a few name·space prefixes, with the following meanings :⁠— | Prefix | Expansion | | ---------: | :-------------------------------------------- | | `catalog:` | `urn:oasis:names:tc:entity:xmlns:xml:catalog` | | `exsl:` | `http://exslt.org/common` | | `exslstr:` | `http://exslt.org/strings` | | `html:` | `http://www.w3.org/1999/xhtml` | | `svg:` | `http://www.w3.org/2000/svg` | | `xlink:` | `http://www.w3.org/1999/xlink` | | `xslt:` | `http://www.w3.org/1999/XSL/Transform` | | `书社:` | `urn:fdc:ladys.computer:20231231:Shu1She4` | ## Setup and Configuration ⛩️📰 书社 depends on the following programs to run. In every case, you may supply your own implementation by overriding the corresponding (allcaps) variable (e·g, set `MKDIR` to supply your own `mkdir` implementation). - `awk` - `cat` - `cksum` - `cp` - `date` - `echo` - `file` - `find` - `git` (optional; set `GIT=` to disable) - `grep` - `ln` - `mkdir` (requires support for `-p`) - `mv` - `od` (requires support for `-t x1`) - `pax` (only when generating archives) - `printf` - `rm` - `sed` - `sleep` - `stat` (BSD *or* GNU) - `test` - `touch` - `tr` (requires support for `-d`) - `uuencode` (requires support for `-m` and `-r`) - `uudecode` (requires support for `-m` and `-r`) - `xargs` (requires support for `-0`) - `xmlcatalog` (provided by `libxml2`) - `xmllint` (provided by `libxml2`) - `xsltproc` (provided by `libxslt`) The following additional variables can be used to control the behaviour of ⛩️📰 书社 :⁠— - **`SRCDIR`:** The location of the source files (default: `sources`). Multiple source directories can be provided, so long as the same file subpath doesn’t exist in more than one of them. - **`INCLUDEDIR`:** The location of source includes (default: `sources/includes`). This can be inside of `SRCDIR`, but needn’t be. Multiple include directories can be provided, so long as the same file subpath doesn’t exist in more than one of them. - **`BUILDDIR`:** The location of the (temporary) build directory (default: `build`). `make clean` will delete this, and it is recommended that it not be used for programs aside from ⛩️📰 书社. - **`DESTDIR`:** The location of directory to output files to (default: `public`). `make install` will overwrite files in this directory which correspond to those in `SRCDIR`. It *will not* touch other files, including those generated from files in `SRCDIR` which have since been deleted. Files are first compiled to `$(BUILDDIR)/public` before they are copied to `DESTDIR`, so this folder is relatively quick and inexpensive to re·create. It’s reasonable to simply delete it before every `make install` to ensure stale content is removed. - **`THISDIR`:** The location of the ⛩️📰 书社 `GNUmakefile`. This should be set automatically when calling Make and shouldn’t ever need to be set manually. This variable is used to find the ⛩️📰 书社 `lib/` folder, which is expected to be in the same location. - **`MAGIC`:** A white·space‐separated list of magic files to use (default: `$(THISDIR)/magic/*`). - **`EXTRAMAGIC`:** The value of this variable is appended to `MAGIC` by default, to enable additional magic files without overriding the existing ones. - **`FINDRULES`:** Rules to use with `find` when searching for source files. The default ignores files that start with a period or hyphen‐minus, those which end with a cloparen, and those which contain a hash, buck, percent, asterisk, colon, semi, eroteme, bracket, backslash, or pipe. - **`EXTRAFINDRULES`:** The value of this variable is appended to `FINDRULES` by default, to enable additional rules without overriding the existing ones. - **`FINDINCLUDERULES`:** Rules to use with `find` when searching for includes (default: `$(FINDRULES)`). - **`EXTRAFINDINCLUDERULES`:** The value of this variable is appended to `FINDINCLUDERULES` by default, to enable additional rules without overriding the existing ones. - **`PARSERS`:** A white·space‐separated list of parsers to use (default: `$(THISDIR)/parsers/*.xslt`). - **`EXTRAPARSERS`:** The value of this variable is appended to `PARSERS` by default, to enable additional parsers without overriding the existing ones. - **`TRANSFORMS`:** A white·space‐separated list of transforms to use (default: `$(THISDIR)/transforms/*.xslt`). - **`EXTRATRANSFORMS`:** The value of this variable is appended to `TRANSFORMS` by default, to enable additional transforms without overriding the existing ones. - **`XMLTYPES`:** A white·space‐separated list of media types to consider X·M·L (default: `application/xml text/xml`). - **`THISREV`:** The current version of ⛩️📰 书社 (default: derived from the current git tag/branch/commit). - **`SRCREV`:** The current version of the source files (default: derived from the current git tag/branch/commit). - **`VERBOSE`:** If this variable has a value, every recipe instruction will be printed when it runs (default: empty). This is helpful for debugging, but typically too noisy for general usage. ## Source Files Source files may be placed in `SRCDIR` in any manner; the file structure used there will match the output. The type of source files is *not* determined by file extension, but rather by magic number; this means that files **must** begin with something recognizable. Supported magic numbers include :⁠— - `` element whose `@type` gives its media type, and then passed to the parser to process. Source files whose media type does not have an associated X·S·L·T parser are considered “assets” and will not be transformed. **☡ For compatibility with this program, source file·names must not contain Ascii white·space, colons (`:`), semis (`;`), pipes (`|`), bucks (`$`), percents (`%`), hashes (`#`), asterisks (`*`), brackets (`[` or `]`), erotemes (`?`), backslashes (`\`), or control characters, must not begin with a hyphen‐minus (`-`), and must not end with a cloparen (`)`).** The former characters have the potential to conflict with make syntax, a leading hyphen‐minus is confusable for a command‐line argument, and a trailing cloparen [activates a bug in G·N·U Make 3.81](https://stackoverflow.com/questions/17148468/capturing-filenames-including-parentheses-with-gnu-makes-wildcard-function#comment24825307_17148894). ## Parsers Parsers are used to convert plaintext files into X·M·L trees, as well as convert plaintext formats which are already included inline in existing source X·M·L documents. ⛩️📰 书社 comes with some parsers; namely :⁠— - **`parsers/plain.xslt`:** Wraps `text/plain` contents in a `` element. - **`parsers/record-jar.xslt`:** Converts `text/record-jar` contents into a `` of `` elements (one for each record). - **`parsers/tsv.xslt`:** Converts `text/tab-separated-values` contents into an `` element. New ⛩️📰 书社 parsers which target plaintext formats should have an `` element with no `@name` or `@mode` and whose `@match` attribute… - Starts with an appropriately‐name·spaced qualified name for a `` element. - Follows this with the string `[@type=`. - Follows this with a quoted string giving a media type supported by the parser. Media type parameters are *not* supported. - Follows this with the string `]`. For example, the trivial `text/plain` parser is defined as follows :⁠— ```xml <书社:id>example:text/plain ``` ⛩️📰 书社 will scan the provided parsers for this pattern to determine the set of allowed plaintext file types. Multiple such `` elements may be provided in a single parser, for example if the parser supports multiple media types. Alternatively, you can set the `@书社:supported-media-types` attribute on the root element of the parser to override media type support detection. Even when `@书社:supported-media-types` is set, it is a requirement that each parser transform any `` elements with a `@type` which matches their registered types into something else. Otherwise the parser will be stuck in an endless loop. The result tree of applying the transform to the `` element will be reparsed (in case any new `` elements were added in its subtree), and a `@书社:parsed-by` attribute will be added to each toplevel element in the result. The value of this attribute will be the value of the `<书社:id>` toplevel element in the parser. It is possible for parsers to support zero plaintext types. This is useful when targeting specific dialects of X·M·L; parsers in this sense operate on the same basic principles as transforms (described below). The major distinction between X·M·L parsers and transforms is where in the process the transformation happens: Parsers are applied *prior* to embedding (and can be used to generate embeds); transforms are applied *after*. It is **strongly recommended** that auxillary templates in parsers be name·spaced (by `@name` or `@mode`) whenever possible, to avoid conflicts between parsers. ### Attributes added during parsing ⛩️📰 书社 will add a few attributes to the output of the parsing step, namely :⁠— - A `@书社:cksum` attribute on toplevel result elements, giving the `cksum` checksum of the corresponding source file. - For the elements which result from parsing plaintext `` elements :⁠— - A `@书社:parsed-by` attribute, giving a space‐separated list of parsers which parsed the node. (Generally, this will be a list of one, but it is possible for the result of a parse to be another plaintext node, which may be parsed by a different parser.) - A `@书社:media-type` attribute, giving the identified media type of the plaintext node. ## Embedding Documents can be embedded in other documents using a `<书社:link>` element with `@xlink:show="embed"`. The `@xlink:href`s of these elements should have the format `about:shushe?source=`, where `` provides the path to the file within `SRCDIR`. Includes, which do not generate outputs of their own but may still be freely embedded, instead use the format `about:shushe?include=`, where `` provides the path within `INCLUDEDIR`. Embeds are replaced with the parsed contents of a file, unless the file is an asset, in which case an `` element is produced instead (with the contents of the asset file provided as a base64 `data:` u·r·i). Embed replacements will be given a `@书社:identifier` attribute whose value will match the `@xlink:href` of the embed. Embedding takes place after parsing but before transformation, so parsers are able to generate their own embeds. ⛩️📰 书社 is able to detect the transitive embed dependencies of files and update them accordingly; it will signal an error if the dependencies are recursive. ## Output Redirection By default, ⛩️📰 书社 installs files to the same location in `DESTDIR` as they were placed in their `SRCDIR`. This behaviour can be customized by setting the `@书社:destination` attribute on the root element, whose value can give a different path. This attribute is read after parsing, but before transformation (where it is silently dropped). ## Transforms Transforms are used to convert X·M·L files into their final output, after all necessary parsing and embedding has taken place. ⛩️📰 书社 comes with some transforms; namely :⁠— - **`transforms/asset.xslt`:** Converts `` elements which correspond to recognized media types into the appropriate H·T·M·L elements, and deletes `` elements from the body of the document and moves them to the head. - **`transforms/metadata.xslt`:** Provides basic `` metadata. This metadata is generated from `` elements with one of the following `@itemprop` attributes :⁠— - **`urn:fdc:ladys.computer:20231231:Shu1She4:title`:** Provides the title of the page. ⛩️📰 书社 automatically encapsulates H·T·M·L embeds so that their metadata does not propogate up to the embedding document. To undo this behaviour, remove the `@itemscope` and `@itemtype` attributes from the embed during the transformation phase. - **`transforms/serialization.xslt`:** Replaces `<书社:serialize-xml>` elements with the (escaped) serialized X·M·L of their contents. This replacement happens during the application phase, after most other transformations have taken place. If a `@with-namespaces` attribute is provided, any name·space nodes on the toplevel serialized elements whose U·R·I’s correspond to the definitions of the provided prefixes, as defined for the `<书社:serialize-xml>` element, will be declared using name·space attributes on the serialized elements. Otherwise, only name·space nodes which _differ_ from the definitions on the `<书社:serialize-xml>` element will be declared. The string `#default` may be used to represent the default name·space. Multiple prefixes may be provided, separated by white·space. When it comes to name·spaces used internally by ⛩️📰 书社, the prefix used by ⛩️📰 书社 may be declared _in addition to_ the prefix(es) used in the source document(s). It is not possible to selectively only declare one prefix for a name·space to the exclusion of others. `<书社:raw-output>` elements may be used inside of `<书社:serialize-xml>` elements to inject raw output into the serialized X·M·L. The following are recommendations on effective creation of transforms :⁠— - Make template matchers as specific as possible. It is likely an error if two transforms have templates which match the same element (unless the templates have different priority). - Name·space templates (with `@name` or `@mode`) whenever possible. - Set `@exclude-result-prefixes` on the root `xslt:transform` element to reduce the number of declared name·spaces in the final result. ## Global Params The following params are made available globally in parsers and transforms :⁠— - **`BUILDTIME`:** The current time. - **`CKSUM`:** The checksum of the source file (⅌ `cksum`). - **`IDENTIFIER`:** The ⛩️📰 书社 identifier of the source file (a u·r·i beginning with `about:shushe`). - **`SRCREV`:** The value of the `SRCREV` variable (if present). - **`SRCTIME`:** The time at which the source file was last modified. - **`THISREV`:** The value of the `THISREV` variable (if present). The following params are only available in transforms :⁠— - **`CATALOG`:** The path of the catalog file (within `BUILDDIR`). - **`PATH`:** The path of the output file (within `DESTDIR`). ## Output Wrapping ⛩️📰 书社 will wrap the final output of the transforms in appropriate `` and `` elements, so it is not necessary for transforms to do this explicitly. After performing the initial transform, ⛩️📰 书社 will match the root node of the result in the following modes to fill in areas of the wrapper :⁠— - **`书社:header`:** The result of matching in this mode is prepended into the `` of the output (before the transformation result). - **`书社:footer`:** The result of matching in this mode is appended into the `` of the output (after the transformation result). - **`书社:metadata`:** The result of matching in this mode is inserted into the `` of the output. In addition to being called with the transform result, each of these modes will additionally be called with a `` element corresponding to each transform. If a transform has a `<书社:id>` top‐level element whose value is an i·r·i, its `` element will have a corresponding `@书社:id` attribute. This mechanism can be used to allow transforms to insert content without matching any elements in the result; for example, the following transform adds a link to a stylesheet to the `` of every page :⁠— ```xml <书社:id>example:add-stylesheet-links.xslt ``` Output wrapping can be entirely disabled by adding a `@书社:disable-output-wrapping` attribute to the top‐level element in the result tree. It will not be performed on outputs whose root elements are `<书社:archive>`, `<书社:base64-binary>`, or `<书社:raw-text>` (described below). ## Applying Attributes The `<书社:apply-attributes>` element will apply any attributes on the element to the element(s) it wraps. It is especially useful in combination with embeds. The `<书社:apply-attributes-to-root>` element will apply any attributes on the element to the root node of the final transformation result. It is especially useful in combination with output wrapping. In both cases, attributes from various sources are combined with white·space between them. Attribute application takes place after all ordinary transforms have completed. Both elements ignore attributes in the `xml:` name·space, except for `@xml:lang`, which ignores all but the first definition (including any already present on the root element). On H·T·M·L and S·V·G elements, `@lang` has the same behaviour as `@xml:lang`. ## Other Kinds of Output There are a few special elements in the `书社:` name·space which, if they appear as the toplevel element in a transformation result, cause ⛩️📰 书社 to produce something other than an X·M·L file. They are :⁠— - **`<书社:archive>`:** Each child element with a `@书社:archived-as` attribute will be archived as a separate file in a resulting tarball (this attribute gives the file name). These elements will be processed the same as the root elements of any other file (e·g, they will be wrapped; they can themselves specify non X·M·L output types, ⁊·c). Other child elements will be ignored. - **`<书社:base64-binary>`:** The text nodes in the transformation result will, after removing all Ascii whitespace, be treated as a Base·64 string, which is then decoded. - **`<书社:raw-text>`:** A plaintext (U·T·F‐8) file will be produced from the text nodes in the transformation result. ## License This repository conforms to [REUSE][]. Most source files are licensed under the terms of the Mozilla Public License, version 2.0. [REUSE]: [draft-phillips-record-jar-01]: