X-Git-Url: https://git.ladys.computer/Shushe/blobdiff_plain/c430638b245e4ff141c7b6c69d64f87d4d163e9f..964a6521326c8630f5589de971afaac5f6d68870:/README.markdown diff --git a/README.markdown b/README.markdown index 8e56f29..95f6954 100644 --- a/README.markdown +++ b/README.markdown @@ -91,14 +91,17 @@ 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` - `cp` - `date` - `echo` - `file` - `find` +- `git` (optional; set `GIT=` to disable) - `mkdir` (requires support for `-p`) - `mv` +- `od` (requires support for `-t x1`) - `printf` - `rm` - `sed` @@ -108,6 +111,7 @@ In every case, you may supply your own implementation by overriding the - `touch` - `tr` (requires support for `-d`) - `uuencode` (requires support for `-m` and `-r`) +- `xargs` (requires support for `-0`) - `xmlcatalog` (provided by `libxml2`) - `xmllint` (provided by `libxml2`) - `xsltproc` (provided by `libxslt`) @@ -154,17 +158,11 @@ The following additional variables can be used to control the behaviour - **`MAGICDIR`:** The location of the magic files to use (default: `$(THISDIR)/magic`). -- **`FINDOPTS`:** - Options to pass to `find` when searching for source files (default: - `-PE`). - - **`FINDRULES`:** - Rules to use with `find` when searching for source files (default: - `-flags -nohidden -and -not -name '.*'`). - -- **`FINDINCLUDEOPTS`:** - Options to pass to `find` when searching for includes (default: - `$(FINDOPTS)`). + 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, percent, + bracket, hash, asterisk, eroteme, semi, or colon. - **`FINDINCLUDERULES`:** Rules to use with `find` when searching for includes (default: @@ -210,11 +208,13 @@ 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 should not - contain Ascii whitespace or any of the following Ascii characters: - ``!"#$%&()-:<>?\^`{|}``. -These characters are either invalid in u·r·i’s or conflict with aspects - of the Make or commandline syntax. +**☡ For compatibility with this program, source file·names must not + contain Ascii white·space, colons (`:`), semis (`;`), pipes (`|`), + bucks (`$`), percents (`%`), hashes (`#`), asterisks (`*`), brackets + (`[` or `]`), erotemes (`?`), 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. ## Parsers @@ -257,8 +257,10 @@ For example, the trivial `text/plain` parser is defined as follows :⁠— + <书社:id>example:text/plain @@ -273,8 +275,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 @@ -307,6 +322,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, @@ -352,10 +376,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