Update readme documentation

[Shushe] / README.markdown

diff --git a/README.markdown b/README.markdown
index 2dd0eff9a54e61711e6e07238c32e37198e1eeab..28b8b4684366a80c55be6a9ff55065dd640b9ed5 100644 (file)
--- a/README.markdown
+++ b/README.markdown
@@ -93,6 +93,7 @@ In every case, you may supply your own implementation by overriding the
 
 - `cat`
 - `cp`
 
 - `cat`
 - `cp`

+- `date`

 - `echo`
 - `file`
 - `find`
 - `echo`
 - `file`
 - `find`


@@ -102,6 +103,7 @@ In every case, you may supply your own implementation by overriding the
 - `rm`
 - `sed`
 - `sleep`
 - `rm`
 - `sed`
 - `sleep`

+- `stat`

 - `test`
 - `touch`
 - `tr` (requires support for `-d`)
 - `test`
 - `touch`
 - `tr` (requires support for `-d`)


@@ -122,9 +124,21 @@ The following additional variables can be used to control the behaviour
 
 - **`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`.


@@ -175,6 +189,8 @@ Supported magic numbers include :⁠—
 - `#!js` for `text/javascript` files
 - `@charset "` for `text/css` files
 - `#!tsv` for `text/tab-separated-values` files
 - `#!js` for `text/javascript` files
 - `@charset "` for `text/css` files
 - `#!tsv` for `text/tab-separated-values` files

+- `%%` for `text/record-jar` files (unregistered; see
+    [[draft-phillips-record-jar-01][]])

 
 Text formats with associated X·S·L·T parsers are wrapped in a H·T·M·L
   `<script>` element whose `@type` gives its media type, and then
 
 Text formats with associated X·S·L·T parsers are wrapped in a H·T·M·L
   `<script>` element whose `@type` gives its media type, and then


@@ -182,18 +198,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
 


@@ -203,14 +212,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.


@@ -228,13 +243,13 @@ For example, the trivial `text/plain` parser is defined as follows :⁠—
 ```xml
 <?xml version="1.0"?>
 <transform
 ```xml
 <?xml version="1.0"?>
 <transform

-       xmlns="http://www.w3.org/1999/XSL/Transform"
-       xmlns:html="http://www.w3.org/1999/xhtml"
-       version="1.0"
+  xmlns="http://www.w3.org/1999/XSL/Transform"
+  xmlns:html="http://www.w3.org/1999/xhtml"
+  version="1.0"

 >
 >

-       <template match="html:script[@type='text/plain']">
-               <html:pre><value-of select="."/></html:pre>
-       </template>
+  <template match="html:script[@type='text/plain']">
+    <html:pre><value-of select="."/></html:pre>
+  </template>

 </transform>
 ```
 
 </transform>
 ```
 


@@ -242,10 +257,20 @@ For example, the trivial `text/plain` parser is defined as follows :⁠—
   the set of allowed plaintext file types.
 Multiple such `<xslt:template>` elements may be provided in a single
   parser, for example if the parser supports multiple media types.
   the set of allowed plaintext file types.
 Multiple such `<xslt:template>` elements may be provided in a single
   parser, for example if the parser supports multiple media types.

+Alternatively, you can set the `@书社:supported-media-types` attribute
+  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
 


@@ -276,26 +301,33 @@ Transforms are used to convert X·M·L files into their final output,
   after all necessary parsing and embedding has taken place.
 ⛩️📰 书社 comes with some transforms; namely :⁠—
 
   after all necessary parsing and embedding has taken place.
 ⛩️📰 书社 comes with some transforms; namely :⁠—
 

+- **`transforms/attributes.xslt`:**
+  Applies transforms to the children of any `<书社:apply-attributes>`
+    elements, and then applies the attributes of the
+    `<书社:apply-attributes>` to each result child, replacing the
+    element with the result.
+  This is useful in combination with image embeds to apply alt‐text to
+    the resulting `<html:img>`.
+

 - **`transforms/asset.xslt`:**
 - **`transforms/asset.xslt`:**

-  Converts `<html:object type="text/css">` elements into corresponding
-    `<html:link rel="stylesheet">` elements and
-    `<html:object type="text/javascript">` elements into corresponding
-    `<html:script>` elements.
-  This transform enables embedding of `text/css` and `text/javascript`
-    files, which ordinarily are considered assets (as they lack
-    associated parsers).
+  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.

 
 - **`transforms/metadata.xslt`:**
   Provides basic `<html:head>` metadata.
 
 - **`transforms/metadata.xslt`:**
   Provides basic `<html:head>` metadata.

-  This metadata is generated from `<html:meta>` descendants of the
-    first element with an `@itemscope` attribute (recommended to just
-    be the root element).
-  Such elements can provide metadata using the following `@itemprop`
-    attributes :⁠—
+  This metadata is generated from `<html:meta>` elements with one of
+    the following `@itemprop` attributes :⁠—

 
   - **`urn:fdc:ladys.computer:20231231:Shu1She4:title`:**
     Provides the title of the page.
 
 
   - **`urn:fdc:ladys.computer:20231231:Shu1She4:title`:**
     Provides the title of the page.
 

+  ⛩️📰 书社 automatically encapsulates embeds so that their metadata
+    does not propogate up to the embedding document.
+  To undo this behaviour, remove the `@itemscope` and `@itemtype`
+    attributes from the embed during the transformation phase.
+

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


@@ -308,18 +340,68 @@ The following are recommendations on effective creation of
 - Set `@exclude-result-prefixes` on the root `xslt:transform` element
     to reduce the number of declared namespaces in the final result.
 
 - Set `@exclude-result-prefixes` on the root `xslt:transform` element
     to reduce the number of declared namespaces in the final result.
 

+The params `$buildtime`, `$srctime`, and `$path` are available within
+  transforms and are initialized to the current time, the time that the
+  source file was last modified, and the path of the output file within
+  $(DESTDIR).
+

 ## Output Wrapping
 
 ⛩️📰 书社 will wrap the final output of the transforms in appropriate
   `<html:html>` and `<html:body>` elements, so it is not necessary for
   transforms to do this explicitly.
 ## Output Wrapping
 
 ⛩️📰 书社 will wrap the final output of the transforms in appropriate
   `<html:html>` and `<html:body>` elements, so it is not necessary for
   transforms to do this explicitly.

-The `<html:head>` of the output will contain the result tree generated
-  by matching the root node in the `书社:metadata` mode; the provided
-  `transforms/metadata.xslt` transform uses this mode to generate basic
-  metadata, but it is possible for other transforms to add their own.
+After performing the initial transform, ⛩️📰 书社 will match the root
+  node of the result in the following modes to fill in areas of the
+  wrapper :⁠—
+
+- **`书社:header`:**
+  The result of matching in this mode is prepended into the
+    `<html:body>` of the output (before the transformation result).
+
+- **`书社:footer`:**
+  The result of matching in this mode is appended into the
+    `<html:body>` of the output (after the transformation result).
+
+- **`书社:metadata`:**
+  The result of matching in this mode is inserted into the
+    `<html:head>` of the output.
+
+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
+  i·r·i, its `<xslt:import>` 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
+  following transform adds a link to a stylesheet to the `<html:head>`
+  of every page :⁠—
+
+```xml
+<?xml version="1.0"?>
+<transform
+  xmlns="http://www.w3.org/1999/XSL/Transform"
+  xmlns:html="http://www.w3.org/1999/xhtml"
+  xmlns:xslt="http://www.w3.org/1999/XSL/Transform"
+  xmlns:书社="urn:fdc:ladys.computer:20231231:Shu1She4"
+  exclude-result-prefixes="书社"
+  version="1.0"
+>
+  <书社:id>example:add-stylesheet-links.xslt</书社:id>
+  <template match="xslt:include[@书社:id='example:add-stylesheet-links.xslt']" mode="书社:metadata">
+    <html:link rel="stylesheet" type="text/css" href="/style.css"/>
+  </template>
+</transform>
+```
+
+Output wrapping can be entirely disabled by adding a
+  `@书社:disable-output-wrapping` attribute to the top‐level element in
+  the result tree.

 
 ## License
 
 Source files are licensed under the terms of the <cite>Mozilla Public
   License, version 2.0</cite>.
 For more information, see [LICENSE](./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).

+
+[draft-phillips-record-jar-01]: <https://datatracker.ietf.org/doc/html/draft-phillips-record-jar-01>
\ No newline at end of file