X-Git-Url: https://git.ladys.computer/Shushe/blobdiff_plain/a555040fdebc4432aee0c167a89e74ed1378f735..e6e6518e567f7a10533af75c43a479f6ca0b9a5c:/README.markdown?ds=sidebyside diff --git a/README.markdown b/README.markdown index d4399e3..be400b9 100644 --- a/README.markdown +++ b/README.markdown @@ -188,6 +188,7 @@ This document uses a few name·space prefixes, with the following | `exsl:` | `http://exslt.org/common` | | `exslstr:` | `http://exslt.org/strings` | | `html:` | `http://www.w3.org/1999/xhtml` | +| `rdf:` | `http://www.w3.org/1999/02/22-rdf-syntax-ns#` | | `svg:` | `http://www.w3.org/2000/svg` | | `xlink:` | `http://www.w3.org/1999/xlink` | | `xslt:` | `http://www.w3.org/1999/XSL/Transform` | @@ -307,6 +308,12 @@ The following additional variables can be used to control the behaviour default, to enable additional rules without overriding the existing ones. +- **`DATAOPTS`:** + Additional options to use when calling Make during the first stage of a two‐stage build using `DATADIR`. + + This can be used to override variables which are only applicable during the second stage. + Note that when supplying this variable on the shell, it will need to be double‐quoted. + - **`DATAEXT`:** A list of file extensions which signify “data” files during a two‐stage build using `DATADIR`. @@ -541,6 +548,18 @@ These include :⁠— - A `@书社:media-type` attribute, giving the identified media type of the plaintext node. +### Parsed metadata + +It is possible to extract metadata from a document at the same time as + it is being parsed. +This is done by creating result elements in the `书社:about` mode; + these should be R·D·F property elements which apply to the conceptual + entity that is the document being parsed. + +During transformation, metadata for the file with identifier `$FILE` + can be read from the children of + `$书社:about//*[@rdf:about=$FILE]/nie:interpretedAs/*`. + ## Output Redirection By default, ⛩📰 书社 installs files to the same location in `DESTDIR` @@ -550,10 +569,14 @@ This behaviour can be customized by setting the `@书社:destination` This attribute is read after parsing, but before transformation (where it is silently dropped). +Multiple destinations can be provided if the same file should be output to multiple places. +The file is retransformed each time, with the value of the `DESTINATION` global param set appropriately. + ## Embedding Documents can be embedded in other documents using a `<书社:link>` - element with `@xlink:show="embed"`. + element with `@xlink:show="embed"` and an `@xlink:actuate` which is + absent or `"none"`. The `@xlink:href`s of these elements should have the format `about:shushe?source=`, where `` provides the path to the file within `SRCDIR`. @@ -561,6 +584,8 @@ 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`. +If `` indicates a directory and ends with a slash (`/`), + everything within that directory will be embedded. Embeds are replaced with the parsed contents of a file, unless the file is an asset, in which case an `` element is produced @@ -600,6 +625,40 @@ These include :⁠— These attributes are used to scope any nested `` elements with `@itemprop` attributes to their containing documents. +## Soft Dependencies + +When a file depends only on the metadata of another file, and not its + contents, it can be added as a soft dependency rather than an embed. +Soft dependencies are indicated using a `<书社:link>` element with an + `@xlink:show` of `"other"`, `"none"`, or absent, and an + `@xlink:actuate` which is absent or `"none"`. +A change to a soft dependency requires a file to be rebuilt, but no + embedding occurs automatically. +Because there is no automatic embedding, soft dependencies are allowed + to be recursive. + +The `@xlink:href`s of soft dependency `<书社:link>`s are processed in + exactly the same fashion as embeds, described above. + +If the value of `@xlink:show` is `"other"`, the soft dependency is + transitive. +Any dependencies of the indicated file which have a `@name` which + matches that of the referencing `<书社:link>` element will also be + treated as soft dependencies. +If no `@name` is given, it is treated as the empty string. + +When a document is embedded directly, all of its soft dependencies are + also treated as soft dependencies of the embedding object. +However, a document is embedded in a transitive soft dependency, the + embed is treated exactly as tho it were itself a transitive soft + dependency. +That means it must have a matching `@name` to be included, and + like·wise for any embeds or soft dependencies it contains. + +If the value of `@xlink:show` is `"none"` or absent, the soft + dependency is not transitive and its own dependencies are not + checked. + ## Transforms Transforms are used to convert X·M·L files into their final output, @@ -614,6 +673,9 @@ Transforms are used to convert X·M·L files into their final output, This conversion happens during the finalization phase, after the main transformation. +- **`transforms/expansion.xslt`:** + Performs embedding, as described above. + - **`transforms/metadata.xslt`:** Provides basic `` metadata. This metadata is generated from `` elements with one of @@ -684,6 +746,28 @@ The following params are made available globally in parsers and - **`THISREV`:** The value of the `THISREV` variable (if present). +In transforms, the following params are additionally available :⁠— + +- **`DESTINATION`:** + The destination being targeted by this transform. + +- **`书社:about`:** + R·D·F metadata about all of the documents ⛩📰 书社 knows about. + Use `$书社:about//*[@rdf:about=$IDENTIFIER]` to get the metadata for + the current document. + +- **`书社:source`:** + The parsed source document being transformed, prior to any expansion. + +- **`书社:expansion`:** + The document after the all embeds have been expanded. + Unavailable during the `书社:expand` stage. + +- **`书社:result`:** + The document after the main set of transformations have been applied. + Only available during the `书社:finalize` stage, where it is used to + apply output wrapping and other clean·up. + ## Output Wrapping Provided at least one toplevel result element belongs to the H·T·M·L