X-Git-Url: https://git.ladys.computer/Shushe/blobdiff_plain/12c64c8b59e7e572988aa4fa39964043bdf67bfe..HEAD:/README.markdown?ds=inline diff --git a/README.markdown b/README.markdown index 31a7333..70a9730 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,50 @@ 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`. + +- **`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 +359,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 +376,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,7 +617,7 @@ 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 + This conversion happens during the finalization phase, after the main transformation. - **`transforms/metadata.xslt`:** @@ -566,7 +636,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 @@ -692,8 +762,8 @@ It is especially useful in combination with output wrapping. In both cases, attributes from various sources are combined with whiteĀ·space between them. -Attribute application takes place after all ordinary transforms have - completed. +Attribute application takes place after each stage of the + transformation, including after the initial embedding phase. Both elements ignore attributes in the `xml:` nameĀ·space, except for `@xml:lang`, which ignores all but the first definition (including