Re·order remakes to (again) fix restarts

[Shushe] / README.markdown

diff --git a/README.markdown b/README.markdown
index 84c320639c5d95a387f1c29248dc79ac33d06b0c..5b5b84c458c5103e9e748ae29a362255fa84a224 100644 (file)
--- a/README.markdown
+++ b/README.markdown
@@ -228,13 +228,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>
 ```
 
@@ -277,25 +277,24 @@ Transforms are used to convert X·M·L files into their final output,
 ⛩️📰 书社 comes with some transforms; namely :⁠—
 
 - **`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 o.
+    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 :⁠—
 
@@ -317,6 +316,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.
@@ -335,20 +342,24 @@ This mechanism can be used to allow transforms to insert content
 ```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"
+  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>
+  <书社: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