X-Git-Url: https://git.ladys.computer/Shushe/blobdiff_plain/7ae7c33964113408bd8cdee445d90f8057159515..33cd26f85eec175028a9e7ced1562e34ff3d15d6:/README.markdown?ds=inline diff --git a/README.markdown b/README.markdown index 55d6f8f..86d57bc 100644 --- a/README.markdown +++ b/README.markdown @@ -21,16 +21,12 @@ It makes things easier by :⁠— - 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`.) + installed on your computer†. -**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. +† Assuming an operating system with a fairly featureful, and + Posix‐compliant, development setup (e·g, macOS). +In fact, on Linux you will probably need to install a few programs: + `libxml2-utils`, `xsltproc`, `sharutils`, and `pax`. ## Nomenclature @@ -52,6 +48,77 @@ The name 书社 was chosen to play on this pun, as In Ascii environments, ⛩️📰 书社 should be written `Shushe`, following the pinyin transliteration. +## Prerequisites + +In most cases, ⛩️📰 书社 aims to require only functionality which is + present in all Posix‐compliant operating systems. +There are a few exceptions. +Details on particular programs are given below; if a program is not + listed, it is assumed that any Posix‐compliant implementation will + work. + +### `file` + +This is a Posix utility, but ⛩️📰 书社 currently depends on + unspecified behaviour. +It requires support for the following additional options :⁠— + +- **`-C`**, when supplied with `-m`, must be useable to compile a + `.mgc` magicfile for use with future invocations of `file`. + +- **`--files-from`** must be useable to provide a file that `file` + should read file·names from, and `-` must be useable in this + context to specify the standard input. + +- **`--mime-type`** must cause `file` to print the internet media type + of the file with no charset parameter. + +- **`--separator`** must be useable to set the separator that `file` + uses to separate file names from types. + +These options are implemented by the + [Fine Free File Command](https://darwinsys.com/file/), which is used + by most operating systems. + +### `git` + +This is not a Posix utility. +Usage of `git` is optional, but recommended (and activated by default). +To disable it, set `GIT=`. + +### `make` + +This is a Posix utility, but ⛩️📰 书社 currently depends on + unspecified behaviour. +⛩️📰 书社 requires specifically the G·N·U version of `make`, and + depends on functionality present in version 3.81 or later. +It is not expected to work in previous versions, or with other + implementations of Make. + +### `pax` + +This is a Posix utility, but not included in the Linux Standard Base or + installed by default in many distributions. +Only `ustar` format support is required. + +### `uudecode` and `uuencode` + +These are Posix utilities, but not included in the Linux Standard Base + or installed by default in many distributions. +The G·N·U [Sharutils](https://www.gnu.org/software/sharutils/) package + can be installed to access them. + +### `xmlcatalog` and `xmllint` + +These are not a Posix utilities. +They is a part of `libxml2`, but may need to be installed separately + (e·g by the name `libxml2-utils`). + +### `xsltproc` + +This is not a Posix utility. +It is a part of `libxslt`, but may need to be installed separately. + ## Basic Usage Place source files in `sources/` and run `make install` to compile @@ -75,7 +142,7 @@ Compilation involves the following steps :⁠— 6. ⛩️📰 书社 compiles each output file to `build/result`. -7. ⛩️📰 书社 symlinks most output files from `build/result` to +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. @@ -87,19 +154,23 @@ As this is a Make‐based program, steps will only be run if the corresponding buildfile or output file is older than its prerequisites. -## Namespaces +## Name·spaces -The ⛩️📰 书社 namespace is `urn:fdc:ladys.computer:20231231:Shu1She4`. +The ⛩️📰 书社 name·space is `urn:fdc:ladys.computer:20231231:Shu1She4`. -This document uses a few namespace prefixes, with the following +This document uses a few name·space prefixes, with the following meanings :⁠— -| Prefix | Expansion | -| -------: | :----------------------------------------- | -| `html:` | `http://www.w3.org/1999/xhtml` | -| `xlink:` | `http://www.w3.org/1999/xlink` | -| `xslt:` | `http://www.w3.org/1999/XSL/Transform` | -| `书社:` | `urn:fdc:ladys.computer:20231231:Shu1She4` | +| 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 @@ -113,26 +184,26 @@ In every case, you may supply your own implementation by overriding the - `cksum` - `cp` - `date` -- `echo` - `file` - `find` - `git` (optional; set `GIT=` to disable) +- `grep` - `ln` -- `mkdir` (requires support for `-p`) +- `ls` +- `mkdir` - `mv` -- `od` (requires support for `-t x1`) +- `od` - `pax` (only when generating archives) - `printf` - `rm` - `sed` - `sleep` -- `stat` - `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`) +- `tr` +- `uuencode` +- `uudecode` +- `xargs` - `xmlcatalog` (provided by `libxml2`) - `xmllint` (provided by `libxml2`) - `xsltproc` (provided by `libxslt`) @@ -264,11 +335,11 @@ Source files whose media type does not have an associated X·S·L·T 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 (`)`).** + 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 + a leading hyphen‐minus is confusable for a commandline 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 @@ -293,7 +364,7 @@ New ⛩️📰 书社 parsers which target plaintext formats should have an `` element with no `@name` or `@mode` and whose `@match` attribute… -- Starts with an appropriately‐namespaced qualified name for a +- Starts with an appropriately‐name·spaced qualified name for a `` element. - Follows this with the string `[@type=`. @@ -350,7 +421,7 @@ 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 - namespaced (by `@name` or `@mode`) whenever possible, to avoid + name·spaced (by `@name` or `@mode`) whenever possible, to avoid conflicts between parsers. ### Attributes added during parsing @@ -432,6 +503,33 @@ Transforms are used to convert X·M·L files into their final output, 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 :⁠— @@ -439,10 +537,10 @@ The following are recommendations on effective creation of It is likely an error if two transforms have templates which match the same element (unless the templates have different priority). -- Namespace templates (with `@name` or `@mode`) whenever possible. +- 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 namespaces in the final result. + to reduce the number of declared name·spaces in the final result. ## Global Params @@ -464,6 +562,10 @@ The following params are made available globally in parsers and - **`SRCTIME`:** The time at which the source file was last modified. + Due to limitations in Posix, this time will only have minute + precision if the file was modified in the last six months, and will + only have day precision if the file is older. + Users should not expect this value to be particularly stable. - **`THISREV`:** The value of the `THISREV` variable (if present). @@ -547,7 +649,7 @@ In both cases, attributes from various sources are combined with Attribute application takes place after all ordinary transforms have completed. -Both elements ignore attributes in the `xml:` namespace, except for +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 @@ -555,7 +657,7 @@ On H·T·M·L and S·V·G elements, `@lang` has the same behaviour as ## Other Kinds of Output -There are a few special elements in the `书社:` namespace which, if +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 :⁠— @@ -569,6 +671,13 @@ They are :⁠— non X·M·L output types, ⁊·c). Other child elements will be ignored. + If the `<书社:archive>` element is given an `@书社:expanded` + attribute, rather than producing a tarball ⛩️📰 书社 will output + the directory which expanding the tarball would produce. + This mechanism can be used to generate multiple files from a single + source, provided all of the files are contained with·in the same + directory. + - **`<书社: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