Stylistic readme edits

diff --git a/README.markdown b/README.markdown
index be400b9e2b9a4c9d9e24830dc5d53977e6fe7b0e..658866e02a7d9e78c026c567b4f98472e7cef217 100644 (file)
--- a/README.markdown
+++ b/README.markdown
@@ -1,5 +1,5 @@
 <!--
 <!--

-SPDX-FileCopyrightText: 2024, 2025 Lady <https://www.ladys.computer/about/#lady>
+SPDX-FileCopyrightText: 2024, 2025, 2026 Lady <https://www.ladys.computer/about/#lady>

 SPDX-License-Identifier: CC0-1.0
 -->
 # ⛩📰 书社
 SPDX-License-Identifier: CC0-1.0
 -->
 # ⛩📰 书社


@@ -70,7 +70,7 @@ Macintosh systems somewhat interestingly implement this option
   extensions rather than standardized.][rdar-92753335]
 Despite this, the default Macintosh implementation will still work with
   ⛩📰 书社, with the caveat that the timestamp will only include a
   extensions rather than standardized.][rdar-92753335]
 Despite this, the default Macintosh implementation will still work with
   ⛩📰 书社, with the caveat that the timestamp will only include a

-  fractional component when a Posix⹀compliant (e·g, Macintosh legacy or
+  fractional component when a Posix‐compliant (e·g, Macintosh legacy or

   G·N·U) implementation is used.
 
 ### `file`
   G·N·U) implementation is used.
 
 ### `file`


@@ -93,9 +93,8 @@ It requires support for the following additional options :⁠—
 - **`--separator`** must be useable to set the separator that `file`
     uses to separate file names from types.
 
 - **`--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.
+These options are implemented by the [Fine Free File Command][F3C],
+  which is used by most operating systems.

 
 ### `git`
 
 
 ### `git`
 


@@ -125,8 +124,7 @@ These are Posix utilities, but they were considered optional in
   `POSIX.1-2001` (altho they are made mandatory in `POSIX.1-2008`) and
   they are not included in the Linux Standard Base or installed by
   default in many distributions.
   `POSIX.1-2001` (altho they are made mandatory in `POSIX.1-2008`) and
   they are 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
-  provides one implementation.
+The G·N·U [Sharutils][] package provides one implementation.

 
 ### `xmlcatalog` and `xmllint`
 
 
 ### `xmlcatalog` and `xmllint`
 


@@ -246,12 +244,19 @@ The following additional variables can be used to control the behaviour
     file subpath doesn’t exist in more than one of them.
 
 - **`DATADIR`:**
     file subpath doesn’t exist in more than one of them.
 
 - **`DATADIR`:**

-  If set to the location of a directory, ⛩📰 书社 will run a two‐stage build.
-  In the first stage, only files in `SRCDIR` which match `FINDDATARULES` (see below) will be built, with files in `DATADIR` serving as includes.
-  In the second stage, the remaining files in `SRCDIR` will be built, with the files built during the first stage, in addition to any files in `INCLUDEDIR`, serving as includes.
-  Files built during the first stage are copied into `DESTDIR` alongside those from the second stage when installing.
-
-  This functionality is intended for sites where the bulk of the site can be built from a few data files which are expensive to create.
+  If set to the location of a directory, ⛩📰 书社 will run a two‐stage
+    build.
+  In the first stage, only files in `SRCDIR` which match
+    `FINDDATARULES` (see below) will be built, with files in `DATADIR`
+    serving as includes.
+  In the second stage, the remaining files in `SRCDIR` will be built,
+    with the files built during the first stage, in addition to any
+    files in `INCLUDEDIR`, serving as includes.
+  Files built during the first stage are copied into `DESTDIR`
+    alongside those from the second stage when installing.
+
+  This functionality is intended for sites where the bulk of the site
+    can be built from a few data files which are expensive to create.

 
 - **`BUILDDIR`:**
   The location of the (temporary) build directory (default: `build`).
 
 - **`BUILDDIR`:**
   The location of the (temporary) build directory (default: `build`).


@@ -262,18 +267,19 @@ The following additional variables can be used to control the behaviour
   The location of directory to output files to (default: `public`).
   `make install` will overwrite files in this directory which
     correspond to those in `SRCDIR`.
   The location of directory to output files to (default: `public`).
   `make install` will overwrite files in this directory which
     correspond to those in `SRCDIR`.

-  It *will not* touch other files, including those generated from files
+  It _will not_ touch other files, including those generated from files

     in `SRCDIR` which have since been deleted.
 
   Files are first compiled to `$(BUILDDIR)/public` before they are
     copied to `DESTDIR`, so this folder is relatively quick and
     inexpensive to re·create.
   It’s reasonable to simply delete it before every `make install` to
     in `SRCDIR` which have since been deleted.
 
   Files are first compiled to `$(BUILDDIR)/public` before they are
     copied to `DESTDIR`, so this folder is relatively quick and
     inexpensive to re·create.
   It’s reasonable to simply delete it before every `make install` to

-    ensure stale content is removed.
+    ensure stale content is removed, assuming copies are quick on your
+    file·system.

 
 - **`THISDIR`:**
   The location of the ⛩📰 书社 `GNUmakefile`.
 
 - **`THISDIR`:**
   The location of the ⛩📰 书社 `GNUmakefile`.

-  This should be set automatically when calling Make and shouldn’t ever
+  This should be set automatically when calling Make and shouldn¦t ever

     need to be set manually.
   This variable is used to find the ⛩📰 书社 `lib/` folder, which is
     expected to be in the same location.
     need to be set manually.
   This variable is used to find the ⛩📰 书社 `lib/` folder, which is
     expected to be in the same location.


@@ -284,7 +290,8 @@ The following additional variables can be used to control the behaviour
 
 - **`EXTRAMAGIC`:**
   The value of this variable is appended to `MAGIC` by default, to
 
 - **`EXTRAMAGIC`:**
   The value of this variable is appended to `MAGIC` by default, to

-    enable additional magic files without overriding the existing ones.
+    enable additional magic files without overriding the existing
+    ones (default: empty).

 
 - **`FINDRULES`:**
   Rules to use with `find` when searching for source files.
 
 - **`FINDRULES`:**
   Rules to use with `find` when searching for source files.


@@ -297,7 +304,8 @@ The following additional variables can be used to control the behaviour
 
 - **`EXTRAFINDRULES`:**
   The value of this variable is appended to `FINDRULES` by default, to
 
 - **`EXTRAFINDRULES`:**
   The value of this variable is appended to `FINDRULES` by default, to

-    enable additional rules without overriding the existing ones.
+    enable additional rules without overriding the existing ones
+    (default: empty).

 
 - **`FINDINCLUDERULES`:**
   Rules to use with `find` when searching for includes (default:
 
 - **`FINDINCLUDERULES`:**
   Rules to use with `find` when searching for includes (default:


@@ -306,16 +314,20 @@ The following additional variables can be used to control the behaviour
 - **`EXTRAFINDINCLUDERULES`:**
   The value of this variable is appended to `FINDINCLUDERULES` by
     default, to enable additional rules without overriding the existing
 - **`EXTRAFINDINCLUDERULES`:**
   The value of this variable is appended to `FINDINCLUDERULES` by
     default, to enable additional rules without overriding the existing

-    ones.
+    ones (default: empty).

 
 - **`DATAOPTS`:**
 
 - **`DATAOPTS`:**

-  Additional options to use when calling Make during the first stage of a two‐stage build using `DATADIR`.
+  Additional options to use when calling Make during the first stage of
+    a two‐stage build using `DATADIR` (default: empty).

 
 

-  This can be used to override variables which are only applicable during the second stage.
-  Note that when supplying this variable on the shell, it will need to be double‐quoted.
+  This can be used to override variables which are only applicable
+    during the second stage.
+  Note that when supplying this variable on the shell, it will need to
+    be twice‐quoted.

 
 - **`DATAEXT`:**
 
 - **`DATAEXT`:**

-  A list of file extensions which signify “data” files during a two‐stage build using `DATADIR`.
+  A list of file extensions which signify “data” files during a
+    two‐stage build using `DATADIR`  (default: `rdf`).

 
 - **`FINDDATARULES`:**
   Rules to use with `find` when searching for data files.
 
 - **`FINDDATARULES`:**
   Rules to use with `find` when searching for data files.


@@ -324,33 +336,49 @@ The following additional variables can be used to control the behaviour
 - **`EXTRAFINDDATARULES`:**
   The value of this variable is appended to `FINDDATARULES` by
     default, to enable additional rules without overriding the existing
 - **`EXTRAFINDDATARULES`:**
   The value of this variable is appended to `FINDDATARULES` by
     default, to enable additional rules without overriding the existing

-    ones.
+    ones (default: empty).

 
 - **`FINDFILTERONLY`:**
 
 - **`FINDFILTERONLY`:**

-  A semicolon‐separated list of regular expressions, at least one of which the paths for sources and includes are required to match, unless empty (default: empty).
+  A semicolon‐separated list of regular expressions, at least one of
+    which the paths for sources and includes are required to match,
+    unless empty (default: empty).

 
 - **`FINDFILTEROUT`:**
 
 - **`FINDFILTEROUT`:**

-  A semicolon‐separated list of regular expressions, each of which matches paths that should _not_ be considered sources or includes (default: empty).
+  A semicolon‐separated list of regular expressions, each of which
+    matches paths that should _not_ be considered sources or includes
+    (default: empty).

 
 - **`FINDINCLUDEFILTERONLY`:**
 
 - **`FINDINCLUDEFILTERONLY`:**

-  A semicolon‐separated list of regular expressions, at least one of which the paths for includes are required to match, unless empty (default: empty).
+  A semicolon‐separated list of regular expressions, at least one of
+    which the paths for includes are required to match, unless empty
+    (default: empty).

 
 

-  Note that only paths which already match `FINDFILTERONLY` are considered.
+  Note that only paths which already match `FINDFILTERONLY` are
+    considered.

 
 - **`FINDINCLUDEFILTEROUT`:**
 
 - **`FINDINCLUDEFILTEROUT`:**

-  A semicolon‐separated list of regular expressions, each of which matches paths that should _not_ be considered includes, but may still be considered sources (default: empty).
+  A semicolon‐separated list of regular expressions, each of which
+    matches paths that should _not_ be considered includes, but may
+    still be considered sources (default: empty).

 
 - **`FINDFILTERONLYEXTENDED`:**
 
 - **`FINDFILTERONLYEXTENDED`:**

-  If non·empty, `FINDFILTERONLY` is an extended regular expression; otherwise, it is basic (default: empty).
+  If non·empty, `FINDFILTERONLY` is an extended regular expression;
+    otherwise, it is basic (default: empty).

 
 - **`FINDFILTEROUTEXTENDED`:**
 
 - **`FINDFILTEROUTEXTENDED`:**

-  If non·empty, `FINDFILTEROUT` is an extended regular expression; otherwise, it is basic (default: matches `FINDFILTERONLYEXTENDED`).
+  If non·empty, `FINDFILTEROUT` is an extended regular expression;
+    otherwise, it is basic (default: matches `FINDFILTERONLYEXTENDED`).

 
 - **`FINDINCLUDEFILTERONLYEXTENDED`:**
 
 - **`FINDINCLUDEFILTERONLYEXTENDED`:**

-  If non·empty, `FINDINCLUDEFILTERONLY` is an extended regular expression; otherwise, it is basic (default: matches `FINDFILTERONLYEXTENDED`).
+  If non·empty, `FINDINCLUDEFILTERONLY` is an extended regular
+    expression; otherwise, it is basic (default: matches
+    `FINDFILTERONLYEXTENDED`).

 
 - **`FINDINCLUDEFILTEROUTEXTENDED`:**
 
 - **`FINDINCLUDEFILTEROUTEXTENDED`:**

-  If non·empty, `FINDINCLUDEFILTEROUT` is an extended regular expression; otherwise, it is basic (default: `1` if either `FINDFILTEROUTEXTENDED` or `FINDINCLUDEFILTERONLYEXTENDED` is non·empty).
+  If non·empty, `FINDINCLUDEFILTEROUT` is an extended regular
+    expression; otherwise, it is basic (default: `1` if either
+    `FINDFILTEROUTEXTENDED` or `FINDINCLUDEFILTERONLYEXTENDED` is
+    non·empty).

 
 - **`PARSERS`:**
   A white·space‐separated list of parsers to use (default:
 
 - **`PARSERS`:**
   A white·space‐separated list of parsers to use (default:


@@ -358,7 +386,8 @@ The following additional variables can be used to control the behaviour
 
 - **`EXTRAPARSERS`:**
   The value of this variable is appended to `PARSERS` by default, to
 
 - **`EXTRAPARSERS`:**
   The value of this variable is appended to `PARSERS` by default, to

-    enable additional parsers without overriding the existing ones.
+    enable additional parsers without overriding the existing ones
+    (default: empty).

 
 - **`PARSERLIBS`:**
   A white·space‐separated list of parser dependencies (default:
 
 - **`PARSERLIBS`:**
   A white·space‐separated list of parser dependencies (default:


@@ -367,7 +396,7 @@ The following additional variables can be used to control the behaviour
 - **`EXTRAPARSERLIBS`:**
   The value of this variable is appended to `PARSERLIBS` by default, to
     enable additional parser dependencies without overriding the
 - **`EXTRAPARSERLIBS`:**
   The value of this variable is appended to `PARSERLIBS` by default, to
     enable additional parser dependencies without overriding the

-    existing ones.
+    existing ones (default: empty).

 
 - **`TRANSFORMS`:**
   A white·space‐separated list of transforms to use (default:
 
 - **`TRANSFORMS`:**
   A white·space‐separated list of transforms to use (default:


@@ -375,7 +404,8 @@ The following additional variables can be used to control the behaviour
 
 - **`EXTRATRANSFORMS`:**
   The value of this variable is appended to `TRANSFORMS` by default, to
 
 - **`EXTRATRANSFORMS`:**
   The value of this variable is appended to `TRANSFORMS` by default, to

-    enable additional transforms without overriding the existing ones.
+    enable additional transforms without overriding the existing ones
+    (default: empty).

 
 - **`TRANSFORMLIBS`:**
   A white·space‐separated list of transform dependencies (default:
 
 - **`TRANSFORMLIBS`:**
   A white·space‐separated list of transform dependencies (default:


@@ -384,7 +414,7 @@ The following additional variables can be used to control the behaviour
 - **`EXTRATRANSFORMLIBS`:**
   The value of this variable is appended to `TRANSFORMLIBS` by default,
     to enable additional transform dependencies without overriding the
 - **`EXTRATRANSFORMLIBS`:**
   The value of this variable is appended to `TRANSFORMLIBS` by default,
     to enable additional transform dependencies without overriding the

-    existing ones.
+    existing ones (default: empty).

 
 - **`XMLTYPES`:**
   A white·space‐separated list of media types or media type suffixes to
 
 - **`XMLTYPES`:**
   A white·space‐separated list of media types or media type suffixes to


@@ -422,7 +452,7 @@ The following additional variables can be used to control the behaviour
 
 Source files may be placed in `SRCDIR` in any manner; the file
   structure used there will match the output.
 
 Source files may be placed in `SRCDIR` in any manner; the file
   structure used there will match the output.

-The type of source files is *not* determined by file extension, but
+The type of source files is _not_ determined by file extension, but

   rather by magic number; this means that files **must** begin with
   something recognizable.
 Supported magic numbers include :⁠—
   rather by magic number; this means that files **must** begin with
   something recognizable.
 Supported magic numbers include :⁠—


@@ -449,7 +479,7 @@ Source files whose media type does not have an associated X·S·L·T
 The former characters have the potential to conflict with make syntax,
   a leading hyphen‐minus is confusable for a commandline argument, and a
   trailing cloparen [activates a bug in G·N·U Make
 The former characters have the potential to conflict with make syntax,
   a leading hyphen‐minus is confusable for a commandline 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).
+  3.81][so-17148468-comment].

 
 ## Parsers
 
 
 ## Parsers
 


@@ -480,7 +510,7 @@ New ⛩📰 书社 parsers which target plaintext formats should have an
 
 - Follows this with a quoted string giving a media type supported by
     the parser.
 
 - Follows this with a quoted string giving a media type supported by
     the parser.

-  Media type parameters are *not* supported.
+  Media type parameters are _not_ supported.

 
 - Follows this with the string `]`.
 
 
 - Follows this with the string `]`.
 


@@ -520,16 +550,19 @@ The result tree of applying the transform to the `<html:script>`
 The value of this attribute will be the value of the `<书社:id>`
   toplevel element in the parser.
 
 The value of this attribute will be the value of the `<书社:id>`
   toplevel element in the parser.
 

+Parsers **should** have an `<书社:id>` and, if present, it **must** be
+  unique.
+

 It is possible for parsers to support zero plaintext types.
 This is useful when targeting specific dialects of X·M·L; parsers in
   this sense operate on the same basic principles as transforms
   (described below).
 The major distinction between X·M·L parsers and transforms is where in
   the process the transformation happens:
 It is possible for parsers to support zero plaintext types.
 This is useful when targeting specific dialects of X·M·L; parsers in
   this sense operate on the same basic principles as transforms
   (described below).
 The major distinction between X·M·L parsers and transforms is where in
   the process the transformation happens:

-Parsers are applied *prior* to embedding (and can be used to generate
-  embeds); transforms are applied *after*.
+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
+It is **strongly recommended** that auxiliary templates in parsers be

   name·spaced (by `@name` or `@mode`) whenever possible, to avoid
   conflicts between parsers.
 
   name·spaced (by `@name` or `@mode`) whenever possible, to avoid
   conflicts between parsers.
 


@@ -668,8 +701,8 @@ Transforms are used to convert X·M·L files into their final output,
 - **`transforms/asset.xslt`:**
   Converts `<html:object>` elements which correspond to recognized
     media types into the appropriate H·T·M·L elements, and deletes
 - **`transforms/asset.xslt`:**
   Converts `<html:object>` elements which correspond to recognized
     media types into the appropriate H·T·M·L elements, and deletes

-    `<html:style>` elements from the body of the document and moves
-    them to the head.
+    `<html:style>` elements from the body of the document while
+    transferring them to the head.

   This conversion happens during the finalization phase, after the main
     transformation.
 
   This conversion happens during the finalization phase, after the main
     transformation.
 


@@ -685,7 +718,7 @@ Transforms are used to convert X·M·L files into their final output,
     Provides the title of the page.
 
   ⛩📰 书社 automatically encapsulates H·T·M·L embeds so that their
     Provides the title of the page.
 
   ⛩📰 书社 automatically encapsulates H·T·M·L embeds so that their

-    metadata does not propogate up to the embedding document.
+    metadata does not propagate up to the embedding document.

   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.
 


@@ -888,6 +921,9 @@ This repository conforms to [REUSE][].
 Most source files are licensed under the terms of the <cite>Mozilla
   Public License, version 2.0</cite>.
 
 Most source files are licensed under the terms of the <cite>Mozilla
   Public License, version 2.0</cite>.
 

+[F3C]: <https://darwinsys.com/file/>

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

+[Sharutils]: <https://www.gnu.org/software/sharutils/>

 [draft-phillips-record-jar-01]: <https://datatracker.ietf.org/doc/html/draft-phillips-record-jar-01>
 [rdar-92753335]: <https://github.com/apple-oss-distributions/patch_cmds/blob/5084833f90df1b0e0924ea56f94c0199b3b8bbc6/diff/diffreg.c#L1800-L1808>
 [draft-phillips-record-jar-01]: <https://datatracker.ietf.org/doc/html/draft-phillips-record-jar-01>
 [rdar-92753335]: <https://github.com/apple-oss-distributions/patch_cmds/blob/5084833f90df1b0e0924ea56f94c0199b3b8bbc6/diff/diffreg.c#L1800-L1808>

+[so-17148468-comment]: <https://stackoverflow.com/questions/17148468/capturing-filenames-including-parentheses-with-gnu-makes-wildcard-function#comment24825307_17148894>