Redirect messages to stderr & support disabling

[Shushe] / README.markdown

diff --git a/README.markdown b/README.markdown
index 9523a8a1ae61b8a7090efd7472a17527345cfc1f..3375b8a36eb7b7bcdc63e078d6676da0c71f7708 100644 (file)
--- a/README.markdown
+++ b/README.markdown
@@ -23,26 +23,10 @@ It makes things easier by :⁠—
 It aims to do this with zero dependencies beyond the programs already
   installed on your computer†.
 
 It aims to do this with zero dependencies beyond the programs already
   installed on your computer†.
 

-† The only non‐Posix programs‡ required (other than G·N·U Make itself,
-    and optionally Git) are those provided by `libxml2` and `libxslt`.
-On most operating systems, these libraries come pre·installed, but on
-  Linux machines the commandline utilities are often packaged
-  separately (as **`libxml2-utils`** and **`xsltproc`**), which may
-  still need to be installed.
-Additionally, not all Linux distributions bundle all necessary Posix
-  programs; on Debian (for example) you may need to separately install
-  **`sharutils`** for `uudecode` and `uuencode` and **`pax`** for
-  archiving.
-
-‡ This make·file also currently depends on non‐Posix `stat` but
-  attempts to handle both the G·N·U and B·S·D variants.
-It expects `xargs` to accept a `-0` option, which, while widely
-  supported, is not a part of the Posix standard.
-
-**Note:**
-⛩️📰 书社 requires functionality present in G·N·U Make 3.81 or later,
-  and will not work in previous versions, or with other implementations
-  of Make.
+† Assuming an operating system with a fairly featureful, and
+  Posix‐compliant, development setup (e·g, macOS).
+In fact, on Linux you will probably need to install a few programs:
+  `libxml2-utils`, `xsltproc`, `sharutils`, and `pax`.

 
 ## Nomenclature
 
 
 ## Nomenclature
 


@@ -64,6 +48,77 @@ The name <i lang="cmn-Hans">书社</i> was chosen to play on this pun, as
 In Ascii environments, ⛩️📰 书社 should be written `Shushe`, following
   the pinyin transliteration.
 
 In Ascii environments, ⛩️📰 书社 should be written `Shushe`, following
   the pinyin transliteration.
 

+## Prerequisites
+
+In most cases, ⛩️📰 书社 aims to require only functionality which is
+  present in all Posix‐compliant operating systems.
+There are a few exceptions.
+Details on particular programs are given below; if a program is not
+  listed, it is assumed that any Posix‐compliant implementation will
+  work.
+
+### `file`
+
+This is a Posix utility, but ⛩️📰 书社 currently depends on
+  unspecified behaviour.
+It requires support for the following additional options :⁠—
+
+- **`-C`**, when supplied with `-m`, must be useable to compile a
+    `.mgc` magicfile for use with future invocations of `file`.
+
+- **`--files-from`** must be useable to provide a file that `file`
+    should read file·names from, and `-` must be useable in this
+    context to specify the standard input.
+
+- **`--mime-type`** must cause `file` to print the internet media type
+    of the file with no charset parameter.
+
+- **`--separator`** must be useable to set the separator that `file`
+    uses to separate file names from types.
+
+These options are implemented by the
+  [Fine Free File Command](https://darwinsys.com/file/), which is used
+  by most operating systems.
+
+### `git`
+
+This is not a Posix utility.
+Usage of `git` is optional, but recommended (and activated by default).
+To disable it, set `GIT=`.
+
+### `make`
+
+This is a Posix utility, but ⛩️📰 书社 currently depends on
+  unspecified behaviour.
+⛩️📰 书社 requires specifically the G·N·U version of `make`, and
+  depends on functionality present in version 3.81 or later.
+It is not expected to work in previous versions, or with other
+  implementations of Make.
+
+### `pax`
+
+This is a Posix utility, but not included in the Linux Standard Base or
+  installed by default in many distributions.
+Only `ustar` format support is required.
+
+### `uudecode` and `uuencode`
+
+These are Posix utilities, but not included in the Linux Standard Base
+  or installed by default in many distributions.
+The G·N·U [Sharutils](https://www.gnu.org/software/sharutils/) package
+  can be installed to access them.
+
+### `xmlcatalog` and `xmllint`
+
+These are not a Posix utilities.
+They is a part of `libxml2`, but may need to be installed separately
+  (e·g by the name `libxml2-utils`).
+
+### `xsltproc`
+
+This is not a Posix utility.
+It is a part of `libxslt`, but may need to be installed separately.
+

 ## Basic Usage
 
 Place source files in `sources/` and run `make install` to compile
 ## Basic Usage
 
 Place source files in `sources/` and run `make install` to compile


@@ -129,7 +184,6 @@ In every case, you may supply your own implementation by overriding the
 - `cksum`
 - `cp`
 - `date`
 - `cksum`
 - `cp`
 - `date`

-- `echo`

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


@@ -144,13 +198,12 @@ In every case, you may supply your own implementation by overriding the
 - `rm`
 - `sed`
 - `sleep`
 - `rm`
 - `sed`
 - `sleep`

-- `stat` (BSD *or* GNU)

 - `test`
 - `touch`
 - `tr`
 - `uuencode`
 - `uudecode`
 - `test`
 - `touch`
 - `tr`
 - `uuencode`
 - `uudecode`

-- `xargs` (requires support for `-0`)
+- `xargs`

 - `xmlcatalog` (provided by `libxml2`)
 - `xmllint` (provided by `libxml2`)
 - `xsltproc` (provided by `libxslt`)
 - `xmlcatalog` (provided by `libxml2`)
 - `xmllint` (provided by `libxml2`)
 - `xsltproc` (provided by `libxslt`)


@@ -239,8 +292,8 @@ The following additional variables can be used to control the behaviour
     enable additional transforms without overriding the existing ones.
 
 - **`XMLTYPES`:**
     enable additional transforms without overriding the existing ones.
 
 - **`XMLTYPES`:**

-  A white·space‐separated list of media types to consider X·M·L
-    (default: `application/xml text/xml`).
+  A white·space‐separated list of media types or media type suffixes to
+    consider X·M·L (default: `application/xml text/xml +xml`).

 
 - **`THISREV`:**
   The current version of ⛩️📰 书社 (default: derived from the current
 
 - **`THISREV`:**
   The current version of ⛩️📰 书社 (default: derived from the current


@@ -250,6 +303,15 @@ The following additional variables can be used to control the behaviour
   The current version of the source files (default: derived from the
     current git tag/branch/commit).
 
   The current version of the source files (default: derived from the
     current git tag/branch/commit).
 

+- **`QUIET`:**
+  If this variable has a value, informative messages will not be
+    printed (default: empty).
+  Informative messages print to stderr, not stdout, so disabling them
+    usually shouldn’t be necessary.
+  This does not (cannot) disable messages from Make itself, for which
+    the `-s`, `--silent` ∕ `--quiet` Make option is more likely to be
+    useful.
+

 - **`VERBOSE`:**
   If this variable has a value, every recipe instruction will be
     printed when it runs (default: empty).
 - **`VERBOSE`:**
   If this variable has a value, every recipe instruction will be
     printed when it runs (default: empty).


@@ -282,14 +344,12 @@ Source files whose media type does not have an associated X·S·L·T
   contain Ascii white·space, colons (`:`), semis (`;`), pipes (`|`),
   bucks (`$`), percents (`%`), hashes (`#`), asterisks (`*`), brackets
   (`[` or `]`), erotemes (`?`), backslashes (`\`), or control
   contain Ascii white·space, colons (`:`), semis (`;`), pipes (`|`),
   bucks (`$`), percents (`%`), hashes (`#`), asterisks (`*`), brackets
   (`[` or `]`), erotemes (`?`), backslashes (`\`), or control

-  characters, must not begin with a hyphen‐minus (`-`), must not end
-  with a cloparen (`)`), and must not contain quoted braces (`"{` or
-  `}"`).**
+  characters, must not begin with a hyphen‐minus (`-`), and must not end
+  with a cloparen (`)`).**

 The former characters have the potential to conflict with make syntax,
 The former characters have the potential to conflict with make syntax,

-  a leading hyphen‐minus is confusable for a command‐line argument, a
+  a leading hyphen‐minus is confusable for a commandline argument, and a

   trailing cloparen [activates a bug in G·N·U Make
   trailing cloparen [activates a bug in G·N·U Make

-  3.81](https://stackoverflow.com/questions/17148468/capturing-filenames-including-parentheses-with-gnu-makes-wildcard-function#comment24825307_17148894),
-  and quoted braces are used internally by the program.
+  3.81](https://stackoverflow.com/questions/17148468/capturing-filenames-including-parentheses-with-gnu-makes-wildcard-function#comment24825307_17148894).

 
 ## Parsers
 
 
 ## Parsers
 


@@ -511,6 +571,10 @@ The following params are made available globally in parsers and
 
 - **`SRCTIME`:**
   The time at which the source file was last modified.
 
 - **`SRCTIME`:**
   The time at which the source file was last modified.

+  Due to limitations in Posix, this time will only have minute
+    precision if the file was modified in the last six months, and will
+    only have day precision if the file is older.
+  Users should not expect this value to be particularly stable.

 
 - **`THISREV`:**
   The value of the `THISREV` variable (if present).
 
 - **`THISREV`:**
   The value of the `THISREV` variable (if present).


@@ -616,6 +680,13 @@ They are :⁠—
     non X·M·L output types, ⁊·c).
   Other child elements will be ignored.
 
     non X·M·L output types, ⁊·c).
   Other child elements will be ignored.
 

+  If the `<书社:archive>` element is given an `@书社:expanded`
+    attribute, rather than producing a tarball ⛩️📰 书社 will output
+    the directory which expanding the tarball would produce.
+  This mechanism can be used to generate multiple files from a single
+    source, provided all of the files are contained with·in the same
+    directory.
+

 - **`<书社:base64-binary>`:**
   The text nodes in the transformation result will, after removing all
     Ascii whitespace, be treated as a Base·64 string, which is then
 - **`<书社:base64-binary>`:**
   The text nodes in the transformation result will, after removing all
     Ascii whitespace, be treated as a Base·64 string, which is then


@@ -625,29 +696,6 @@ They are :⁠—
   A plaintext (U·T·F‐8) file will be produced from the text nodes in
     the transformation result.
 
   A plaintext (U·T·F‐8) file will be produced from the text nodes in
     the transformation result.
 

-## Pagination
-
-It is possible to have a single source file produce multiple output
-  files via `<书社:page>` elements, whose `@name` gives the name of the
-  page.
-If a parsed document has a `@书社:destination` which contains `%s`,
-  the `%s` will be replaced with the `@name` for each `<书社:page>` (and
-  removed for the main output).
-Otherwise, the `@name` is inserted before the first period of the
-  filename (or at the end of the filename for those with no period).
-If `<书社:page>`s do not have a `@name`, they are numbered
-  sequentially.
-The destination of pages must be in the same directory as their parent.
-
-Pagination essentially forms a limited convenience for the more
-  sophisticated technique of creating an archive with ⛩️📰 书社 and
-  then unarchiving it.
-Pages are, from Make’s point of view, untracked side·effects of
-  installing the main output, meaning they cannot be targeted directly
-  and will not appear in `make list` or `make listout`.
-They are intended solely for the like of indices and feeds, for which
-  convenience and necessity outweigh their flaws.
-

 ## License
 
 This repository conforms to [REUSE][].
 ## License
 
 This repository conforms to [REUSE][].