Enable output redirection with 书社:destination

[Shushe] / README.markdown

diff --git a/README.markdown b/README.markdown
index 6bfa987de70458ca7886a79a146b0982858580bd..de822096c943ddfeae790ae9cda2469fd9be43f3 100644 (file)
--- a/README.markdown
+++ b/README.markdown
@@ -91,6 +91,7 @@ In every case, you may supply your own implementation by overriding the
   corresponding (allcaps) variable (e·g, set `MKDIR` to supply your own
   `mkdir` implementation).
 
+- `awk`
 - `cat`
 - `cp`
 - `date`
@@ -99,6 +100,7 @@ In every case, you may supply your own implementation by overriding the
 - `find`
 - `mkdir` (requires support for `-p`)
 - `mv`
+- `od` (requires support for `-t x1`)
 - `printf`
 - `rm`
 - `sed`
@@ -108,6 +110,7 @@ In every case, you may supply your own implementation by overriding the
 - `touch`
 - `tr` (requires support for `-d`)
 - `uuencode` (requires support for `-m` and `-r`)
+- `xargs` (requires support for `-0`)
 - `xmlcatalog` (provided by `libxml2`)
 - `xmllint` (provided by `libxml2`)
 - `xsltproc` (provided by `libxslt`)
@@ -117,10 +120,14 @@ The following additional variables can be used to control the behaviour
 
 - **`SRCDIR`:**
   The location of the source files (default: `sources`).
+  Multiple source directories can be provided, so long as the same
+    file subpath doesn’t exist in more than one of them.
 
 - **`INCLUDEDIR`:**
-  The location of the source files (default: `sources/includes`).
+  The location of source includes (default: `sources/includes`).
   This can be inside of `SRCDIR`, but needn’t be.
+  Multiple include directories can be provided, so long as the same
+    file subpath doesn’t exist in more than one of them.
 
 - **`BUILDDIR`:**
   The location of the (temporary) build directory (default: `build`).
@@ -150,13 +157,14 @@ The following additional variables can be used to control the behaviour
 - **`MAGICDIR`:**
   The location of the magic files to use (default: `$(THISDIR)/magic`).
 
-- **`FINDOPTS`:**
-  Options to pass to `find` when searching for source files (default:
-    `-PE`).
-
 - **`FINDRULES`:**
-  Rules to use with `find` when searching for source files (default:
-    `-flags -nohidden -and -not -name '.*'`).
+  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, or colon.
+
+- **`FINDINCLUDERULES`:**
+  Rules to use with `find` when searching for includes (default:
+    `$(FINDRULES)`).
 
 - **`PARSERS`:**
   A white·space‐separated list of parsers to use (default:
@@ -198,11 +206,12 @@ 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.
 
-For compatibility with this program, source filenames should not
-  contain Ascii whitespace or any of the following Ascii characters:
-  ``!"#$%&()-:<>?\^`{|}``.
-These characters are either invalid in u·r·i’s or conflict with aspects
-  of the Make or commandline syntax.
+**☡ 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 (`-`).**
+The former characters have the potential to conflict with make syntax,
+  and a leading hyphen‐minus is confusable for a command‐line argument.
 
 ## Parsers
 
@@ -295,6 +304,15 @@ Embedding takes place after parsing but before transformation, so
   and update them accordingly; it will signal an error if the
   dependencies are recursive.
 
+## Output Redirection
+
+By default, ⛩️📰 书社 installs files to the same location in `DESTDIR`
+  as they were placed in their `SRCDIR`.
+This behaviour can be customized by setting the `@书社:destination`
+  attribute on the root element, whose value can give a different path.
+This attribute is read after parsing, but before transformation (where
+  it is silently dropped).
+
 ## Transforms
 
 Transforms are used to convert X·M·L files into their final output,
@@ -370,7 +388,7 @@ In addition to being called with the transform result, each of these
   modes will additionally be called with a `<xslt:include>` element
   corresponding to each transform.
 If a transform has a `<书社:id>` top‐level element whose value is an
-  i·r·i, its `<xslt:import>` element will have a corresponding
+  i·r·i, its `<xslt:include>` 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