X-Git-Url: https://git.ladys.computer/Shushe/blobdiff_plain/e4f65cee884c40d631209b5cbb711de161a2969a..6972774d7db8027876c937abf5a7a5b0420d7965:/README.markdown

diff --git a/README.markdown b/README.markdown
index 51aca8d..8e56f29 100644
--- a/README.markdown
+++ b/README.markdown
@@ -93,13 +93,17 @@ In every case, you may supply your own implementation by overriding the
 
 - `cat`
 - `cp`
+- `date`
 - `echo`
 - `file`
 - `find`
 - `mkdir` (requires support for `-p`)
 - `mv`
 - `printf`
+- `rm`
 - `sed`
+- `sleep`
+- `stat`
 - `test`
 - `touch`
 - `tr` (requires support for `-d`)
@@ -113,16 +117,32 @@ The following additional variables can be used to control the behaviour
 
 - **`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`:**
-  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.
+  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`).
+  `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`).
+  `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`.
@@ -136,12 +156,20 @@ The following additional variables can be used to control the behaviour
 
 - **`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 '.*'`).
 
+- **`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`).
@@ -173,6 +201,8 @@ Supported magic numbers include :⁠—
 - `#!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
@@ -180,18 +210,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.
 
-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
 
@@ -201,14 +224,20 @@ Parsers are used to convert plaintext files into X·M·L trees, as well
 ⛩️📰 书社 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`:**
-  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.
@@ -226,13 +255,13 @@ For example, the trivial `text/plain` parser is defined as follows :⁠—
 ```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>
 ```
 
@@ -240,10 +269,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.
+Alternatively, you can set the `@书社:supported-media-types` attribute
+  on the root element of the parser to override media type support
+  detection.
+
+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 all templates in parsers other than
-  those described above be namespaced (by `@name` or `@mode`), to avoid
-  conflicts between templates in multiple parsers.
+It is **strongly recommended** that auxillary templates in parsers be
+  namespaced (by `@name` or `@mode`) whenever possible, to avoid
+  conflicts between parsers.
 
 ## Embedding
 
@@ -274,26 +313,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 :⁠—
 
+- **`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`:**
-  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.
-  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.
 
+  ⛩️📰 书社 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 :⁠—
 
@@ -306,18 +352,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.
 
+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.
-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: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
+  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).
+
+[draft-phillips-record-jar-01]: <https://datatracker.ietf.org/doc/html/draft-phillips-record-jar-01>
\ No newline at end of file