Consider destinations akin to dependencies

[Shushe] / README.markdown

diff --git a/README.markdown b/README.markdown
index 4c1f1d63f57a91b42c40230ce5419aa5aa1b5c6d..3801b7eedeb3ca36e6783cc7f10d4020598502b1 100644 (file)
--- a/README.markdown
+++ b/README.markdown
@@ -98,6 +98,7 @@ In every case, you may supply your own implementation by overriding the
 - `echo`
 - `file`
 - `find`
 - `echo`
 - `file`
 - `find`

+- `git` (optional; set `GIT=` to disable)

 - `mkdir` (requires support for `-p`)
 - `mv`
 - `od` (requires support for `-t x1`)
 - `mkdir` (requires support for `-p`)
 - `mv`
 - `od` (requires support for `-t x1`)


@@ -159,9 +160,9 @@ The following additional variables can be used to control the behaviour
 
 - **`FINDRULES`:**
   Rules to use with `find` when searching for source files.
 
 - **`FINDRULES`:**
   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, or
-    colon.
+  The default ignores files that start with a period or hyphen‐minus
+    and those which contain a hash, buck, percent, asterisk, colon,
+    semi, eroteme, bracket, or pipe.

 
 - **`FINDINCLUDERULES`:**
   Rules to use with `find` when searching for includes (default:
 
 - **`FINDINCLUDERULES`:**
   Rules to use with `find` when searching for includes (default:


@@ -207,10 +208,11 @@ 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.
 
 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 must not
-  contain Ascii whitespace, colons (`:`), pipes (`|`), bucks (`$`),
-  percents (`%`) or control characters, and must not begin with a
-  hyphen‐minus (`-`).**
+**☡ 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.
 
 The former characters have the potential to conflict with make syntax,
   and a leading hyphen‐minus is confusable for a command‐line argument.
 


@@ -255,8 +257,10 @@ For example, the trivial `text/plain` parser is defined as follows :⁠—
 <transform
   xmlns="http://www.w3.org/1999/XSL/Transform"
   xmlns:html="http://www.w3.org/1999/xhtml"
 <transform
   xmlns="http://www.w3.org/1999/XSL/Transform"
   xmlns:html="http://www.w3.org/1999/xhtml"

+  xmlns:书社="urn:fdc:ladys.computer:20231231:Shu1She4"

   version="1.0"
 >
   version="1.0"
 >

+  <书社:id>example:text/plain</书社:id>

   <template match="html:script[@type='text/plain']">
     <html:pre><value-of select="."/></html:pre>
   </template>
   <template match="html:script[@type='text/plain']">
     <html:pre><value-of select="."/></html:pre>
   </template>


@@ -271,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.
 
   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 `<html:script>` 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 `<html:script>`
+  element will be reparsed (in case any new `<html:script>` 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
 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


@@ -359,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.
 
 - 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
 
 
 ## Output Wrapping