Update documentation regarding (non‐)Posix needs

diff --git a/GNUmakefile b/GNUmakefile
index 2cb311f3ce7e09bc7ecd177f546311f97351ccb1..7880926256982e6b877cb88299525d80c7edf359 100644 (file)
--- a/GNUmakefile
+++ b/GNUmakefile
@@ -29,9 +29,9 @@ override define makefileinfo
 ║│ • git (optional)                                           │║
 ║│ • ln                                                       │║
 ║│ • ls                                                       │║
 ║│ • git (optional)                                           │║
 ║│ • ln                                                       │║
 ║│ • ls                                                       │║

-║│ • mkdir (requires support for `-p´)                        │║
+║│ • mkdir                                                    │║

 ║│ • mv                                                       │║
 ║│ • mv                                                       │║

-║│ • od (requires support for `-t x1´)                        │║
+║│ • od                                                       │║

 ║│ • pax (only when generating archives)                      │║
 ║│ • printf                                                   │║
 ║│ • rm                                                       │║
 ║│ • pax (only when generating archives)                      │║
 ║│ • printf                                                   │║
 ║│ • rm                                                       │║


@@ -40,9 +40,9 @@ override define makefileinfo
 ║│ • stat                                                     │║
 ║│ • test                                                     │║
 ║│ • touch                                                    │║
 ║│ • stat                                                     │║
 ║│ • test                                                     │║
 ║│ • touch                                                    │║

-║│ • tr (requires support for `-d´)                           │║
-║│ • uuencode (requires support for `-m´ and `-r´)            │║
-║│ • uudecode (requires support for `-m´ and `-r´)            │║
+║│ • tr                                                       │║
+║│ • uuencode                                                 │║
+║│ • uudecode                                                 │║

 ║│ • xargs (requires support for `-0´)                        │║
 ║│ • xmlcatalog (provided by libxml2)                         │║
 ║│ • xmllint (provided by libxml2)                            │║
 ║│ • xargs (requires support for `-0´)                        │║
 ║│ • xmlcatalog (provided by libxml2)                         │║
 ║│ • xmllint (provided by libxml2)                            │║

diff --git a/README.markdown b/README.markdown
index 9523a8a1ae61b8a7090efd7472a17527345cfc1f..bf353e0f0266f768cac8d2c48b8de8b0426e451c 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,99 @@ 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.
+
+### `date`
+
+This is a Posix utility, but ⛩️📰 书社 currently depends on
+  unspecified behaviour.
+When the G·N·U version of `stat` is being used, then the G·N·U version
+  of `date` is also expected.
+
+### `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.
+
+### `stat`
+
+This is not a Posix utility, and nor is it particularly portable.
+To get around incompatibilities, ⛩️📰 书社 attempts to recognize G·N·U
+  `stat` by searching for the string `GNU` when invoked with the
+  `--version` option, and falls back to B·S·D behaviour otherwise.
+
+### `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.
+
+### `xargs`
+
+This is a Posix utility, but ⛩️📰 书社 currently depends on
+  unspecified behaviour.
+It requires support for the `-0` flag, which must disable the special
+  quote and whitespace handling of `xargs` in favour of null‐terminated
+  strings.
+
+### `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