From: Lady Date: Sun, 14 Apr 2024 19:44:22 +0000 (-0400) Subject: Add support for manually serializing X·M·L X-Git-Tag: 0.7.2~1 X-Git-Url: https://git.ladys.computer/Shushe/commitdiff_plain/3dc36d1f23aff7cb60b498d88e503b619a7bc543 Add support for manually serializing X·M·L This commit adds a transform for a new `<书社:serialize-xml>` element, which is useful in conjunction with `<书社:raw-text>` to produce a more finely‐controlled X·M·L output, or in other X·M·L‐y situations where an escaped X·M·L value is required. The algorithm used for serialization attempts to closely match the DOM Parsing and Serialization spec, including such behaviours as mandating an undeclared `xml:` prefix for the X·M·L name·space and dropping the prefix from elements whose name·space matches the default, but it probably isn’t exactly the same (due in part to the fact that the underlying data structure is an X·M·L infoset, not a potentially dynamically‐modified Dom). No special allowances are made for elements in the H·T·M·L name·space; this is not (yet) a suitable polyglot serializer (or intended to be one). --- diff --git a/README.markdown b/README.markdown index 55d6f8f..643a4d8 100644 --- a/README.markdown +++ b/README.markdown @@ -87,19 +87,23 @@ As this is a Make‐based program, steps will only be run if the corresponding buildfile or output file is older than its prerequisites. -## Namespaces +## Name·spaces -The ⛩️📰 书社 namespace is `urn:fdc:ladys.computer:20231231:Shu1She4`. +The ⛩️📰 书社 name·space is `urn:fdc:ladys.computer:20231231:Shu1She4`. -This document uses a few namespace prefixes, with the following +This document uses a few name·space prefixes, with the following meanings :⁠— -| Prefix | Expansion | -| -------: | :----------------------------------------- | -| `html:` | `http://www.w3.org/1999/xhtml` | -| `xlink:` | `http://www.w3.org/1999/xlink` | -| `xslt:` | `http://www.w3.org/1999/XSL/Transform` | -| `书社:` | `urn:fdc:ladys.computer:20231231:Shu1She4` | +| Prefix | Expansion | +| ---------: | :-------------------------------------------- | +| `catalog:` | `urn:oasis:names:tc:entity:xmlns:xml:catalog` | +| `exsl:` | `http://exslt.org/common` | +| `exslstr:` | `http://exslt.org/strings` | +| `html:` | `http://www.w3.org/1999/xhtml` | +| `svg:` | `http://www.w3.org/2000/svg` | +| `xlink:` | `http://www.w3.org/1999/xlink` | +| `xslt:` | `http://www.w3.org/1999/XSL/Transform` | +| `书社:` | `urn:fdc:ladys.computer:20231231:Shu1She4` | ## Setup and Configuration @@ -293,7 +297,7 @@ New ⛩️📰 书社 parsers which target plaintext formats should have an `` element with no `@name` or `@mode` and whose `@match` attribute… -- Starts with an appropriately‐namespaced qualified name for a +- Starts with an appropriately‐name·spaced qualified name for a `` element. - Follows this with the string `[@type=`. @@ -350,7 +354,7 @@ Parsers are applied *prior* to embedding (and can be used to generate embeds); transforms are applied *after*. It is **strongly recommended** that auxillary templates in parsers be - namespaced (by `@name` or `@mode`) whenever possible, to avoid + name·spaced (by `@name` or `@mode`) whenever possible, to avoid conflicts between parsers. ### Attributes added during parsing @@ -432,6 +436,29 @@ Transforms are used to convert X·M·L files into their final output, To undo this behaviour, remove the `@itemscope` and `@itemtype` attributes from the embed during the transformation phase. +- **`transforms/serialization.xslt`:** + Replaces `<书社:serialize-xml>` elements with the (escaped) + serialized X·M·L of their contents. + This replacement happens during the application phase, after most + other transformations have taken place. + + If a `@with-namespaces` attribute is provided, any name·space nodes + on the toplevel serialized elements whose U·R·I’s correspond to the + definitions of the provided prefixes, as defined for the + `<书社:serialize-xml>` element, will be declared using name·space + attributes on the serialized elements. + Otherwise, only name·space nodes which _differ_ from the definitions + on the `<书社:serialize-xml>` element will be declared. + The string `#default` may be used to represent the default + name·space. + Multiple prefixes may be provided, separated by white·space. + + When it comes to name·spaces used internally by ⛩️📰 书社, the + prefix used by ⛩️📰 书社 may be declared _in addition to_ the + prefix(es) used in the source document(s). + It is not possible to selectively only declare one prefix for a + name·space to the exclusion of others. + The following are recommendations on effective creation of transforms :⁠— @@ -439,10 +466,10 @@ The following are recommendations on effective creation of It is likely an error if two transforms have templates which match the same element (unless the templates have different priority). -- Namespace templates (with `@name` or `@mode`) whenever possible. +- Name·space templates (with `@name` or `@mode`) whenever possible. - Set `@exclude-result-prefixes` on the root `xslt:transform` element - to reduce the number of declared namespaces in the final result. + to reduce the number of declared name·spaces in the final result. ## Global Params @@ -547,7 +574,7 @@ In both cases, attributes from various sources are combined with Attribute application takes place after all ordinary transforms have completed. -Both elements ignore attributes in the `xml:` namespace, except for +Both elements ignore attributes in the `xml:` name·space, except for `@xml:lang`, which ignores all but the first definition (including any already present on the root element). On H·T·M·L and S·V·G elements, `@lang` has the same behaviour as @@ -555,7 +582,7 @@ On H·T·M·L and S·V·G elements, `@lang` has the same behaviour as ## Other Kinds of Output -There are a few special elements in the `书社:` namespace which, if +There are a few special elements in the `书社:` name·space which, if they appear as the toplevel element in a transformation result, cause ⛩️📰 书社 to produce something other than an X·M·L file. They are :⁠— diff --git a/lib/catalog2transform.xslt b/lib/catalog2transform.xslt index 2315762..2b5c417 100644 --- a/lib/catalog2transform.xslt +++ b/lib/catalog2transform.xslt @@ -272,7 +272,7 @@ If a copy of the M·P·L was not distributed with this file, You can obtain one - + @@ -301,7 +301,7 @@ If a copy of the M·P·L was not distributed with this file, You can obtain one - + @@ -309,7 +309,7 @@ If a copy of the M·P·L was not distributed with this file, You can obtain one - + diff --git a/lib/serialize.xslt b/lib/serialize.xslt new file mode 100644 index 0000000..5f792ea --- /dev/null +++ b/lib/serialize.xslt @@ -0,0 +1,257 @@ + + + + + + + + + + + + + diff --git a/transforms/serialization.xslt b/transforms/serialization.xslt new file mode 100644 index 0000000..09f595e --- /dev/null +++ b/transforms/serialization.xslt @@ -0,0 +1,67 @@ + + + + + + <书社:id>urn:fdc:ladys.computer:20231231:Shu1She4:serialization.xslt + +