X-Git-Url: https://git.ladys.computer/Shushe/blobdiff_plain/d71cc3861468e5ce418a3cf3ace5730689e41dce..e5503365cff290808176bec63f9227e5761dee67:/README.markdown diff --git a/README.markdown b/README.markdown index bed7a11..503a163 100644 --- a/README.markdown +++ b/README.markdown @@ -244,6 +244,14 @@ The following additional variables can be used to control the behaviour Multiple include directories can be provided, so long as the same file subpath doesn’t exist in more than one of them. +- **`DATADIR`:** + If set to the location of a directory, ⛩📰 书社 will run a two‐stage build. + In the first stage, only files in `SRCDIR` which match `FINDDATARULES` (see below) will be built, with files in `DATADIR` serving as includes. + In the second stage, the remaining files in `SRCDIR` will be built, with the files built during the first stage, in addition to any files in `INCLUDEDIR`, serving as includes. + Files built during the first stage are copied into `DESTDIR` alongside those from the second stage when installing. + + This functionality is intended for sites where the bulk of the site can be built from a few data files which are expensive to create. + - **`BUILDDIR`:** The location of the (temporary) build directory (default: `build`). `make clean` will delete this, and it is recommended that it not be @@ -299,6 +307,18 @@ The following additional variables can be used to control the behaviour default, to enable additional rules without overriding the existing ones. +- **`DATAEXT`:** + A list of file extensions which signify “data” files during a two‐stage build using `DATADIR`. + +- **`FINDDATARULES`:** + Rules to use with `find` when searching for data files. + By default, these rules are derived from `DATAEXT`. + +- **`EXTRAFINDDATARULES`:** + The value of this variable is appended to `FINDDATARULES` 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`). @@ -307,6 +327,15 @@ The following additional variables can be used to control the behaviour The value of this variable is appended to `PARSERS` by default, to enable additional parsers without overriding the existing ones. +- **`PARSERLIBS`:** + A white·space‐separated list of parser dependencies (default: + `$(THISDIR)/lib/split.xslt`). + +- **`EXTRAPARSERLIBS`:** + The value of this variable is appended to `PARSERLIBS` by default, to + enable additional parser dependencies without overriding the + existing ones. + - **`TRANSFORMS`:** A white·space‐separated list of transforms to use (default: `$(THISDIR)/transforms/*.xslt`). @@ -315,6 +344,15 @@ The following additional variables can be used to control the behaviour The value of this variable is appended to `TRANSFORMS` by default, to enable additional transforms without overriding the existing ones. +- **`TRANSFORMLIBS`:** + A white·space‐separated list of transform dependencies (default: + `$(THISDIR)/lib/serialize.xslt`). + +- **`EXTRATRANSFORMLIBS`:** + The value of this variable is appended to `TRANSFORMLIBS` by default, + to enable additional transform dependencies without overriding the + existing ones. + - **`XMLTYPES`:** A white·space‐separated list of media types or media type suffixes to consider X·M·L (default: `application/xml text/xml +xml`). @@ -547,6 +585,8 @@ Transforms are used to convert X·M·L files into their final output, 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. + This conversion happens during the application phase, after the main + transformation. - **`transforms/metadata.xslt`:** Provides basic `` metadata. @@ -618,18 +658,19 @@ The following params are made available globally in parsers and - **`THISREV`:** The value of the `THISREV` variable (if present). -The following params are only available in transforms :⁠— - -- **`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 +Provided at least one toplevel result element belongs to the H·T·M·L + namespace, ⛩📰 书社 will wrap the final output of the transforms in + appropriate `` and `` elements, so it is not + necessary for transforms to do this explicitly. +If a toplevel result element _is_ a `` and `` + element, it will be merged with the one that ⛩📰 书社 creates. +Consequently, wrapping the result in a `` element can be + used to enable wrapping for non‐H·T·M·L content, when desired. + +As a part of this process, after performing the initial transform + ⛩📰 书社 will match in the following modes to fill in areas of the wrapper :⁠— - **`书社:header`:** @@ -644,16 +685,13 @@ After performing the initial transform, ⛩📰 书社 will match the root 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 :⁠— +The document being matched will contain the full transform result + prior to wrapping as well as an `<书社:id>` element for each + transform. +The latter elements can be matched to enable transforms to provide + 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 @@ -666,7 +704,7 @@ This mechanism can be used to allow transforms to insert content version="1.0" > <书社:id>example:add-stylesheet-links.xslt -