X-Git-Url: https://git.ladys.computer/Shushe/blobdiff_plain/af8b42c720c6aaa54199b556a656d40e8b8951a6..940adb77ae2147d8c62b6ab7afaf292d13ce64de:/README.markdown
diff --git a/README.markdown b/README.markdown
index 84c3206..13cb1d6 100644
--- 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
@@ -228,13 +232,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>
```
@@ -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
@@ -277,25 +284,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 :—
@@ -308,6 +314,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
@@ -317,6 +328,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,22 +354,28 @@ 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
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