X-Git-Url: https://git.ladys.computer/Shushe/blobdiff_plain/587bd5a36e079e0509296ced479488a923663a8e..a555040fdebc4432aee0c167a89e74ed1378f735:/README.markdown?ds=sidebyside diff --git a/README.markdown b/README.markdown index 013e3ed..d4399e3 100644 --- a/README.markdown +++ b/README.markdown @@ -1,5 +1,5 @@ # ā›©šŸ“°Ā ä¹¦ē¤¾ @@ -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,44 @@ 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. + +- **`FINDFILTERONLY`:** + A semicolonā€separated list of regular expressions, at least one of which the paths for sources and includes are required to match, unless empty (default: empty). + +- **`FINDFILTEROUT`:** + A semicolonā€separated list of regular expressions, each of which matches paths that should _not_ be considered sources or includes (default: empty). + +- **`FINDINCLUDEFILTERONLY`:** + A semicolonā€separated list of regular expressions, at least one of which the paths for includes are required to match, unless empty (default: empty). + + Note that only paths which already match `FINDFILTERONLY` are considered. + +- **`FINDINCLUDEFILTEROUT`:** + A semicolonā€separated list of regular expressions, each of which matches paths that should _not_ be considered includes, but may still be considered sources (default: empty). + +- **`FINDFILTERONLYEXTENDED`:** + If nonĀ·empty, `FINDFILTERONLY` is an extended regular expression; otherwise, it is basic (default: empty). + +- **`FINDFILTEROUTEXTENDED`:** + If nonĀ·empty, `FINDFILTEROUT` is an extended regular expression; otherwise, it is basic (default: matches `FINDFILTERONLYEXTENDED`). + +- **`FINDINCLUDEFILTERONLYEXTENDED`:** + If nonĀ·empty, `FINDINCLUDEFILTERONLY` is an extended regular expression; otherwise, it is basic (default: matches `FINDFILTERONLYEXTENDED`). + +- **`FINDINCLUDEFILTEROUTEXTENDED`:** + If nonĀ·empty, `FINDINCLUDEFILTEROUT` is an extended regular expression; otherwise, it is basic (default: `1` if either `FINDFILTEROUTEXTENDED` or `FINDINCLUDEFILTERONLYEXTENDED` is nonĀ·empty). + - **`PARSERS`:** A whiteĀ·spaceā€separated list of parsers to use (default: `$(THISDIR)/parsers/*.xslt`). @@ -307,6 +353,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 +370,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 +611,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 finalization phase, after the main + transformation. - **`transforms/metadata.xslt`:** Provides basic `` metadata. @@ -564,7 +630,7 @@ Transforms are used to convert XĀ·MĀ·L files into their final output, - **`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 + This replacement happens during the finalization phase, after most other transformations have taken place. If a `@with-namespaces` attribute is provided, any nameĀ·space nodes @@ -618,11 +684,6 @@ 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 Provided at least one toplevel result element belongs to the HĀ·TĀ·MĀ·L @@ -651,9 +712,8 @@ As a part of this process, after performing the initial transform `` of the output. The document being matched will contain the full transform result - prior to wrapping as well as an `` element (with an - `@书ē¤¾:id` attribute) for each transform which has a valid - `<书ē¤¾:id>`. + 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 @@ -670,7 +730,7 @@ The latter elements can be matched to enable transforms to provide version="1.0" > <书ē¤¾:id>example:add-stylesheet-links.xslt -