X-Git-Url: https://git.ladys.computer/Shushe/blobdiff_plain/e0c0562b79020c115373957d9c2d92a575758dda..6a2e42ac0e7daa97ee0aecc72ddcff9b288470e2:/README.markdown diff --git a/README.markdown b/README.markdown index 7e9b74b..9d51889 100644 --- a/README.markdown +++ b/README.markdown @@ -1,6 +1,6 @@ # ⛩️📰 书社 -An X·S·L·T‐based static site generator. +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. @@ -18,6 +18,15 @@ It makes things easier by :⁠— 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 @@ -98,6 +107,7 @@ In every case, you may supply your own implementation by overriding the - `echo` - `file` - `find` +- `git` (optional; set `GIT=` to disable) - `mkdir` (requires support for `-p`) - `mv` - `od` (requires support for `-t x1`) @@ -159,8 +169,9 @@ The following additional variables can be used to control the behaviour - **`FINDRULES`:** Rules to use with `find` when searching for source files. - The default ignores hidden files, those that start with a period or - hyphen‐minus, and those which contain a pipe, buck, or colon. + The default ignores files that start with a period or hyphen‐minus + and those which contain a hash, buck, percent, asterisk, colon, + semi, eroteme, bracket, backslash, or pipe. - **`FINDINCLUDERULES`:** Rules to use with `find` when searching for includes (default: @@ -206,10 +217,11 @@ Text formats with associated X·S·L·T parsers are wrapped in a H·T·M·L 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 filenames must not - contain Ascii whitespace, colons (`:`), pipes (`|`), bucks (`$`), - percents (`%`) or control characters, and must not begin with a - hyphen‐minus (`-`).** +**☡ 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, and must not begin with a hyphen‐minus (`-`).** The former characters have the potential to conflict with make syntax, and a leading hyphen‐minus is confusable for a command‐line argument. @@ -254,8 +266,10 @@ For example, the trivial `text/plain` parser is defined as follows :⁠— + <书社:id>example:text/plain @@ -270,8 +284,21 @@ Alternatively, you can set the `@书社:supported-media-types` attribute on the root element of the parser to override media type support detection. -Parsers can also target specific dialects of X·M·L, in which case they - operate on the same basic principles as transforms (described below). +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 @@ -304,6 +331,15 @@ Embedding takes place after parsing but before transformation, so 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, @@ -349,10 +385,32 @@ The following are recommendations on effective creation of - Set `@exclude-result-prefixes` on the root `xslt:transform` element to reduce the number of declared namespaces in the final result. -The params `$buildtime`, `$srctime`, and `$path` are available within - transforms and are initialized to the current time, the time that the - source file was last modified, and the path of the output file within - $(DESTDIR). +## Global Params + +The following params are made available globally in parsers and + transforms :⁠— + +- **`BUILDTIME`:** + The current time. + +- **`SRCREV`:** + The tag or hash of the current commit in the working directory (if + `GIT` is defined and `./.git` exists). + +- **`SRCTIME`:** + The time at which the source file was last modified. + +- **`VERSION`:** + The tag or hash of the current commit in `THISDIR` (if `GIT` is + defined and `$(THISDIR)/.git` exists). + +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 @@ -413,4 +471,4 @@ Source files are licensed under the terms of the Mozilla Public License, version 2.0. For more information, see [LICENSE](./LICENSE). -[draft-phillips-record-jar-01]: \ No newline at end of file +[draft-phillips-record-jar-01]: