Fix base64 output

[Shushe] / README.markdown

diff --git a/README.markdown b/README.markdown
index f6a08642353a226246ec11eaa60b873e764cfb1d..b83d49ecd24272d33ece6f19ec210683e4133492 100644 (file)
--- a/README.markdown
+++ b/README.markdown
@@ -1,3 +1,7 @@
+<!--
+SPDX-FileCopyrightText: 2024 Lady <https://www.ladys.computer/about/#lady>
+SPDX-License-Identifier: CC0-1.0
+-->

 # ⛩️📰 书社
 
 <b>A make·file for X·M·L.</b>
 # ⛩️📰 书社
 
 <b>A make·file for X·M·L.</b>


@@ -17,16 +21,12 @@ It makes things easier by :⁠—
 - Enabling easy inclusion of source files within each other.
 
 It aims to do this with zero dependencies beyond the programs already
 - Enabling easy inclusion of source files within each other.
 
 It aims to do this with zero dependencies beyond the programs already

-  installed on your computer.
-(On Linux machines, you may need to install `libxml2-utils` to get the
-  commandline programs from `libxml2`.)
+  installed on your computer†.

 
 

-**Note:**
-⛩️📰 书社 requires functionality present in G·N·U Make 3.81 (or later)
-  and will not work in previous versions, or other implementations of
-  Make.
-Compatibility with later versions of G·N·U Make is assumed, but not
-  tested.
+† 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
 


@@ -48,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


@@ -69,9 +154,13 @@ Compilation involves the following steps :⁠—
 5. ⛩️📰 书社 uses the dependency tree to establish prerequisites for
     each output file.
 
 5. ⛩️📰 书社 uses the dependency tree to establish prerequisites for
     each output file.
 

-6. ⛩️📰 书社 compiles each output file to `build/public`.
+6. ⛩️📰 书社 compiles each output file to `build/result`.

 
 

-7. ⛩️📰 书社 copies the output files to `public`.
+7. ⛩️📰 书社 copies most output files from `build/result` to
+     `build/public`, but it does some additional processing instead on
+     those which indicate a non‐X·M·L desired final output form.
+
+8. ⛩️📰 书社 copies the final resulting files to `public`.

 
 You can use `make list` to list each identified source file or include
   alongside its computed type and dependencies.
 
 You can use `make list` to list each identified source file or include
   alongside its computed type and dependencies.


@@ -79,19 +168,23 @@ As this is a Make‐based program, steps will only be run if the
   corresponding buildfile or output file is older than its
   prerequisites.
 
   corresponding buildfile or output file is older than its
   prerequisites.
 

-## Namespaces
+## Name·spaces

 
 

-The ⛩️📰 书社 namespace is `urn:fdc:ladys.computer:20231231:Shu1She4`.
+The ⛩️📰 书社 name·space is `urn:fdc:ladys.computer:20231231:Shu1She4`.

 
 

-This document uses a few namespace prefixes, with the following
+This document uses a few name·space prefixes, with the following

   meanings :⁠—
 
   meanings :⁠—
 

-|   Prefix | Expansion                                  |
-| -------: | :----------------------------------------- |
-|  `html:` | `http://www.w3.org/1999/xhtml`             |
-| `xlink:` | `http://www.w3.org/1999/xlink`             |
-|  `xslt:` | `http://www.w3.org/1999/XSL/Transform`     |
-|  `书社:` | `urn:fdc:ladys.computer:20231231:Shu1She4` |
+|     Prefix | Expansion                                     |
+| ---------: | :-------------------------------------------- |
+| `catalog:` | `urn:oasis:names:tc:entity:xmlns:xml:catalog` |
+|    `exsl:` | `http://exslt.org/common`                     |
+| `exslstr:` | `http://exslt.org/strings`                    |
+|    `html:` | `http://www.w3.org/1999/xhtml`                |
+|     `svg:` | `http://www.w3.org/2000/svg`                  |
+|   `xlink:` | `http://www.w3.org/1999/xlink`                |
+|    `xslt:` | `http://www.w3.org/1999/XSL/Transform`        |
+|    `书社:` | `urn:fdc:ladys.computer:20231231:Shu1She4`    |

 
 ## Setup and Configuration
 
 
 ## Setup and Configuration
 


@@ -109,20 +202,24 @@ In every case, you may supply your own implementation by overriding the
 - `file`
 - `find`
 - `git` (optional; set `GIT=` to disable)
 - `file`
 - `find`
 - `git` (optional; set `GIT=` to disable)

+- `grep`

 - `ln`
 - `ln`

-- `mkdir` (requires support for `-p`)
+- `ls`
+- `mkdir`

 - `mv`
 - `mv`

-- `od` (requires support for `-t x1`)
+- `od`
+- `pax` (only when generating archives)

 - `printf`
 - `rm`
 - `sed`
 - `sleep`
 - `printf`
 - `rm`
 - `sed`
 - `sleep`

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

 - `test`
 - `touch`
 - `test`
 - `touch`

-- `tr` (requires support for `-d`)
-- `uuencode` (requires support for `-m` and `-r`)
-- `xargs` (requires support for `-0`)
+- `tr`
+- `uuencode`
+- `uudecode`
+- `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`)


@@ -254,12 +351,14 @@ 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 (`-`), and must not
-  end with a cloparen (`)`).**
+  characters, must not begin with a hyphen‐minus (`-`), must not end
+  with a cloparen (`)`), and must not contain quoted braces (`"{` or
+  `}"`).**

 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, and
-  a 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).
+  a leading hyphen‐minus is confusable for a command‐line argument, a
+  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.

 
 ## Parsers
 
 
 ## Parsers
 


@@ -283,7 +382,7 @@ New ⛩️📰 书社 parsers which target plaintext formats should have an
   `<xslt:template>` element with no `@name` or `@mode` and whose
   `@match` attribute…
 
   `<xslt:template>` element with no `@name` or `@mode` and whose
   `@match` attribute…
 

-- Starts with an appropriately‐namespaced qualified name for a
+- Starts with an appropriately‐name·spaced qualified name for a

     `<html:script>` element.
 
 - Follows this with the string `[@type=`.
     `<html:script>` element.
 
 - Follows this with the string `[@type=`.


@@ -340,7 +439,7 @@ Parsers are applied *prior* to embedding (and can be used to generate
   embeds); transforms are applied *after*.
 
 It is **strongly recommended** that auxillary templates in parsers be
   embeds); transforms are applied *after*.
 
 It is **strongly recommended** that auxillary templates in parsers be

-  namespaced (by `@name` or `@mode`) whenever possible, to avoid
+  name·spaced (by `@name` or `@mode`) whenever possible, to avoid

   conflicts between parsers.
 
 ### Attributes added during parsing
   conflicts between parsers.
 
 ### Attributes added during parsing


@@ -422,6 +521,33 @@ Transforms are used to convert X·M·L files into their final output,
   To undo this behaviour, remove the `@itemscope` and `@itemtype`
     attributes from the embed during the transformation phase.
 
   To undo this behaviour, remove the `@itemscope` and `@itemtype`
     attributes from the embed during the transformation phase.
 

+- **`transforms/serialization.xslt`:**
+  Replaces `<书社:serialize-xml>` elements with the (escaped)
+    serialized X·M·L of their contents.
+  This replacement happens during the application phase, after most
+    other transformations have taken place.
+
+  If a `@with-namespaces` attribute is provided, any name·space nodes
+    on the toplevel serialized elements whose U·R·I’s correspond to the
+    definitions of the provided prefixes, as defined for the
+    `<书社:serialize-xml>` element, will be declared using name·space
+    attributes on the serialized elements.
+  Otherwise, only name·space nodes which _differ_ from the definitions
+    on the `<书社:serialize-xml>` element will be declared.
+  The string `#default` may be used to represent the default
+    name·space.
+  Multiple prefixes may be provided, separated by white·space.
+
+  When it comes to name·spaces used internally by ⛩️📰 书社, the
+    prefix used by ⛩️📰 书社 may be declared _in addition to_ the
+    prefix(es) used in the source document(s).
+  It is not possible to selectively only declare one prefix for a
+    name·space to the exclusion of others.
+
+  `<书社:raw-output>` elements may be used inside of
+    `<书社:serialize-xml>` elements to inject raw output into the
+    serialized X·M·L.
+

 The following are recommendations on effective creation of
   transforms :⁠—
 
 The following are recommendations on effective creation of
   transforms :⁠—
 


@@ -429,10 +555,10 @@ The following are recommendations on effective creation of
   It is likely an error if two transforms have templates which match
     the same element (unless the templates have different priority).
 
   It is likely an error if two transforms have templates which match
     the same element (unless the templates have different priority).
 

-- Namespace templates (with `@name` or `@mode`) whenever possible.
+- Name·space templates (with `@name` or `@mode`) whenever possible.

 
 - Set `@exclude-result-prefixes` on the root `xslt:transform` element
 
 - Set `@exclude-result-prefixes` on the root `xslt:transform` element

-    to reduce the number of declared namespaces in the final result.
+    to reduce the number of declared name·spaces in the final result.

 
 ## Global Params
 
 
 ## Global Params
 


@@ -518,8 +644,9 @@ This mechanism can be used to allow transforms to insert content
 Output wrapping can be entirely disabled by adding a
   `@书社:disable-output-wrapping` attribute to the top‐level element in
   the result tree.
 Output wrapping can be entirely disabled by adding a
   `@书社:disable-output-wrapping` attribute to the top‐level element in
   the result tree.

-This attribute will also prevent wrapping non‐H·T·M·L embeds with an
-  `<html:div>`.
+It will not be performed on outputs whose root elements are
+  `<书社:archive>`, `<书社:base64-binary>`, or `<书社:raw-text>`
+  (described below).

 
 ## Applying Attributes
 
 
 ## Applying Attributes
 


@@ -536,16 +663,66 @@ In both cases, attributes from various sources are combined with
 Attribute application takes place after all ordinary transforms have
   completed.
 
 Attribute application takes place after all ordinary transforms have
   completed.
 

-Both elements ignore attributes in the `xml:` namespace, except for
+Both elements ignore attributes in the `xml:` name·space, except for

   `@xml:lang`, which ignores all but the first definition (including
   any already present on the root element).
 On H·T·M·L and S·V·G elements, `@lang` has the same behaviour as
   `@xml:lang`.
 
   `@xml:lang`, which ignores all but the first definition (including
   any already present on the root element).
 On H·T·M·L and S·V·G elements, `@lang` has the same behaviour as
   `@xml:lang`.
 

+## Other Kinds of Output
+
+There are a few special elements in the `书社:` name·space which, if
+  they appear as the toplevel element in a transformation result, cause
+  ⛩️📰 书社 to produce something other than an X·M·L file.
+They are :⁠—
+
+- **`<书社:archive>`:**
+  Each child element with a `@书社:archived-as` attribute will be
+    archived as a separate file in a resulting tarball (this attribute
+    gives the file name).
+  These elements will be processed the same as the root elements of any
+    other file (e·g, they will be wrapped; they can themselves specify
+    non X·M·L output types, ⁊·c).
+  Other child elements will be ignored.
+
+- **`<书社: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
+    decoded.
+
+- **`<书社:raw-text>`:**
+  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
 
 ## License
 

-Source files are licensed under the terms of the <cite>Mozilla Public
-  License, version 2.0</cite>.
-For more information, see [LICENSE](./LICENSE).
+This repository conforms to [REUSE][].
+
+Most source files are licensed under the terms of the <cite>Mozilla
+  Public License, version 2.0</cite>.

 
 

+[REUSE]: <https://reuse.software/spec/>

 [draft-phillips-record-jar-01]: <https://datatracker.ietf.org/doc/html/draft-phillips-record-jar-01>
 [draft-phillips-record-jar-01]: <https://datatracker.ietf.org/doc/html/draft-phillips-record-jar-01>