Support pagination

[Shushe] / README.markdown

diff --git a/README.markdown b/README.markdown
index e99255b94091ff5b1c8e595172d78ec2301e3102..9523a8a1ae61b8a7090efd7472a17527345cfc1f 100644 (file)
--- a/README.markdown
+++ b/README.markdown
@@ -23,10 +23,12 @@ 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 are those provided by `libxml2`
-  and `libxslt` (which most operating systems provide), but on Linux
-  machines the commandline utilities may need to be installed
-  separately as **`libxml2-utils`** and **`xsltproc`**.
+† 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
 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


@@ -38,11 +40,9 @@ It expects `xargs` to accept a `-0` option, which, while widely
   supported, is not a part of the Posix standard.
 
 **Note:**
   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 other implementations of
-  Make.
-Compatibility with later versions of G·N·U Make is assumed, but not
-  tested.
+⛩️📰 书社 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.

 
 ## Nomenclature
 
 
 ## Nomenclature
 


@@ -135,6 +135,7 @@ In every case, you may supply your own implementation by overriding the
 - `git` (optional; set `GIT=` to disable)
 - `grep`
 - `ln`
 - `git` (optional; set `GIT=` to disable)
 - `grep`
 - `ln`

+- `ls`

 - `mkdir`
 - `mv`
 - `od`
 - `mkdir`
 - `mv`
 - `od`


@@ -281,12 +282,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
 


@@ -622,6 +625,29 @@ 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][].