Percent‐encode filenames when generating u·r·i’s

[Shushe] / README.markdown

diff --git a/README.markdown b/README.markdown
index cafda3aa533ebb233f4538f78ddba6e4b21f22a2..dec092a5d7c59905bf4070c1bae96f8fa9febff4 100644 (file)
--- a/README.markdown
+++ b/README.markdown
@@ -91,6 +91,7 @@ In every case, you may supply your own implementation by overriding the
   corresponding (allcaps) variable (e·g, set `MKDIR` to supply your own
   `mkdir` implementation).
 
   corresponding (allcaps) variable (e·g, set `MKDIR` to supply your own
   `mkdir` implementation).
 

+- `awk`

 - `cat`
 - `cp`
 - `date`
 - `cat`
 - `cp`
 - `date`


@@ -99,6 +100,7 @@ In every case, you may supply your own implementation by overriding the
 - `find`
 - `mkdir` (requires support for `-p`)
 - `mv`
 - `find`
 - `mkdir` (requires support for `-p`)
 - `mv`

+- `od` (requires support for `-t x1`)

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


@@ -108,6 +110,7 @@ In every case, you may supply your own implementation by overriding the
 - `touch`
 - `tr` (requires support for `-d`)
 - `uuencode` (requires support for `-m` and `-r`)
 - `touch`
 - `tr` (requires support for `-d`)
 - `uuencode` (requires support for `-m` and `-r`)

+- `xargs` (requires support for `-0`)

 - `xmlcatalog` (provided by `libxml2`)
 - `xmllint` (provided by `libxml2`)
 - `xsltproc` (provided by `libxslt`)
 - `xmlcatalog` (provided by `libxml2`)
 - `xmllint` (provided by `libxml2`)
 - `xsltproc` (provided by `libxslt`)


@@ -117,16 +120,32 @@ The following additional variables can be used to control the behaviour
 
 - **`SRCDIR`:**
   The location of the source files (default: `sources`).
 
 - **`SRCDIR`:**
   The location of the source files (default: `sources`).

+  Multiple source directories can be provided, so long as the same
+    file subpath doesn’t exist in more than one of them.

 
 - **`INCLUDEDIR`:**
 
 - **`INCLUDEDIR`:**

-  The location of the source files (default: `sources/includes`).
+  The location of source includes (default: `sources/includes`).

   This can be inside of `SRCDIR`, but needn’t be.
   This can be inside of `SRCDIR`, but needn’t be.

+  Multiple include directories can be provided, so long as the same
+    file subpath doesn’t exist in more than one of them.

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

+  `make clean` will delete this, and it is recommended that it not be
+    used for programs aside from ⛩️📰 书社.

 
 - **`DESTDIR`:**
   The location of directory to output files to (default: `public`).
 
 - **`DESTDIR`:**
   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
+    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.

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


@@ -140,12 +159,20 @@ The following additional variables can be used to control the behaviour
 
 - **`FINDOPTS`:**
   Options to pass to `find` when searching for source files (default:
 
 - **`FINDOPTS`:**
   Options to pass to `find` when searching for source files (default:

-    `-LE`).
+    `-PE`).

 
 - **`FINDRULES`:**
   Rules to use with `find` when searching for source files (default:
     `-flags -nohidden -and -not -name '.*'`).
 
 
 - **`FINDRULES`:**
   Rules to use with `find` when searching for source files (default:
     `-flags -nohidden -and -not -name '.*'`).
 

+- **`FINDINCLUDEOPTS`:**
+  Options to pass to `find` when searching for includes (default:
+    `$(FINDOPTS)`).
+
+- **`FINDINCLUDERULES`:**
+  Rules to use with `find` when searching for includes (default:
+    `$(FINDRULES)`).
+

 - **`PARSERS`:**
   A white·space‐separated list of parsers to use (default:
     `$(THISDIR)/parsers/*.xslt`).
 - **`PARSERS`:**
   A white·space‐separated list of parsers to use (default:
     `$(THISDIR)/parsers/*.xslt`).


@@ -186,18 +213,11 @@ Text formats with associated X·S·L·T parsers are wrapped in a H·T·M·L
 Source files whose media type does not have an associated X·S·L·T
   parser are considered “assets” and will not be transformed.
 
 Source files whose media type does not have an associated X·S·L·T
   parser are considered “assets” and will not be transformed.
 

-For compatibility with this program, source filenames should conform to
-  the following rules :⁠—
-
-- They should not start with a hyphen‐minus.
-  This is to prevent confusion between filenames and options on the
-    commandline.
-
-- They should not contain spaces, colons, percent signs, backticks,
-    question marks, hashes, or backslashes.
-
-In general, filenames should be such that they do not require
-  percent‐encoding in the path component of an i·r·i.
+For compatibility with this program, source filenames should not
+  contain Ascii whitespace or any of the following Ascii characters:
+  ``!"#$%&()-:<>?\^`{|}``.
+These characters are either invalid in u·r·i’s or conflict with aspects
+  of the Make or commandline syntax.

 
 ## Parsers
 
 
 ## Parsers
 


@@ -207,14 +227,20 @@ Parsers are used to convert plaintext files into X·M·L trees, as well
 ⛩️📰 书社 comes with some parsers; namely :⁠—
 
 - **`parsers/plain.xslt`:**
 ⛩️📰 书社 comes with some parsers; namely :⁠—
 
 - **`parsers/plain.xslt`:**

-  Wraps `text/plain` contents in a `<html:pre>` element.
+  Wraps `text/plain` contents in a `<html:pre class="plain">` element.
+
+- **`parsers/record-jar.xslt`:**
+  Converts `text/record-jar` contents into a
+    `<html:div class="record-jar">` of `<html:dl>` elements (one for
+    each record).

 
 - **`parsers/tsv.xslt`:**
 
 - **`parsers/tsv.xslt`:**

-  Converts `text/tab-separated-values` contents into an `<html:table>`
-    element.
+  Converts `text/tab-separated-values` contents into an
+    `<html:table class="tsv">` element.

 
 

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

 
 - Starts with an appropriately‐namespaced qualified name for a
     `<html:script>` element.
 
 - Starts with an appropriately‐namespaced qualified name for a
     `<html:script>` element.


@@ -250,9 +276,16 @@ Alternatively, you can set the `@书社:supported-media-types` attribute
   on the root element of the parser to override media type support
   detection.
 
   on the root element of the parser to override media type support
   detection.
 

-It is **strongly recommended** that all templates in parsers other than
-  those described above be namespaced (by `@name` or `@mode`), to avoid
-  conflicts between templates in multiple parsers.
+Parsers can also target specific dialects of X·M·L, in which case they
+  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*.
+
+It is **strongly recommended** that auxillary templates in parsers be
+  namespaced (by `@name` or `@mode`) whenever possible, to avoid
+  conflicts between parsers.

 
 ## Embedding
 
 
 ## Embedding
 


@@ -299,7 +332,7 @@ Transforms are used to convert X·M·L files into their final output,
 
 - **`transforms/metadata.xslt`:**
   Provides basic `<html:head>` metadata.
 
 - **`transforms/metadata.xslt`:**
   Provides basic `<html:head>` metadata.

-  This metadata is generated from `<html:meta>` elements with one o.
+  This metadata is generated from `<html:meta>` elements with one of

     the following `@itemprop` attributes :⁠—
 
   - **`urn:fdc:ladys.computer:20231231:Shu1She4:title`:**
     the following `@itemprop` attributes :⁠—
 
   - **`urn:fdc:ladys.computer:20231231:Shu1She4:title`:**


@@ -352,7 +385,7 @@ In addition to being called with the transform result, each of these
   modes will additionally be called with a `<xslt:include>` element
   corresponding to each transform.
 If a transform has a `<书社:id>` top‐level element whose value is an
   modes will additionally be called with a `<xslt:include>` element
   corresponding to each transform.
 If a transform has a `<书社:id>` top‐level element whose value is an

-  i·r·i, its `<xslt:import>` element will have a corresponding
+  i·r·i, its `<xslt:include>` element will have a corresponding

   `@书社:id` attribute.
 This mechanism can be used to allow transforms to insert content
   without matching any elements in the result; for example, the
   `@书社:id` attribute.
 This mechanism can be used to allow transforms to insert content
   without matching any elements in the result; for example, the