X-Git-Url: https://git.ladys.computer/Shushe/blobdiff_plain/e7c797ffb120c0dac9be13b28d533d49d164b6d0..edacd9742b9feb3d3d6e10f41b6b077cb51e8002:/README.markdown diff --git a/README.markdown b/README.markdown index 2dd0eff..f2cfdd9 100644 --- a/README.markdown +++ b/README.markdown @@ -175,6 +175,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 +230,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 +279,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 :— @@ -313,13 +314,58 @@ The following are recommendations on effective creation of ⛩️📰 书社 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). + +[draft-phillips-record-jar-01]: <https://datatracker.ietf.org/doc/html/draft-phillips-record-jar-01> \ No newline at end of file