Force removal of existing directories

[Shushe] / README.markdown

diff --git a/README.markdown b/README.markdown
index 9523a8a1ae61b8a7090efd7472a17527345cfc1f..d459604c1709aaf9632bf19b1600e85521461d1f 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,91 @@ 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.
+
+### `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 +198,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)


@@ -150,7 +218,7 @@ In every case, you may supply your own implementation by overriding the
 - `tr`
 - `uuencode`
 - `uudecode`
 - `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`)


@@ -616,6 +684,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