Explicitly declare UTF-8 output for all transforms

[Shushe] / README.markdown

diff --git a/README.markdown b/README.markdown
index 2bb1bcea0e82631c09c3f6249b5eaa635f27beac..cafda3aa533ebb233f4538f78ddba6e4b21f22a2 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`
+- `date`
 - `echo`
 - `file`
 - `find`
@@ -102,6 +103,7 @@ In every case, you may supply your own implementation by overriding the
 - `rm`
 - `sed`
 - `sleep`
+- `stat`
 - `test`
 - `touch`
 - `tr` (requires support for `-d`)
@@ -175,6 +177,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
@@ -242,6 +246,9 @@ 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.
 
 It is **strongly recommended** that all templates in parsers other than
   those described above be namespaced (by `@name` or `@mode`), to avoid
@@ -276,14 +283,19 @@ 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.
@@ -310,6 +322,11 @@ 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
@@ -319,6 +336,14 @@ 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.
@@ -351,8 +376,14 @@ This mechanism can be used to allow transforms to insert content
 </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