 |
   |
|
|
TransParam.xsl — Enables parametrised transclusion.
[defRole]
defRole (URI) — A URI which identifies the transclusion XLink role. Default is http://stanleysecurity.github.io/PACBook/role/transclusion.
An XML document containing transclusion definitions and references.
An XML document, identical to the input except that transclusion references are replaced by their definitions.
This stylesheet enables you to transclude small snippets of XML; for example, to insert a product name at multiple locations in the document. It is complementary to the standard XML methods of transclusion using XInclude, in that it enables you to redefine text replacements locally. It is based on early versions of the proposed standard for DocBook transclusion.
To define XML snippets for transclusion (definitions) create an extended link element with the specified transclusion role URI in the metadata at the start of the document. Within
this extended link element add XLink resource elements which contain the XML text or elements for transclusion. (To refer
to an external set of definitions, use XInclude to transclude the parameter definitions into the document!) Each XLink resource
must have an xl:label attribute which enables you to refer to this resource.
To redefine resources locally, e.g. within a single section of the document, add new XLink resources in the same way to the metadata at the start of that section.
To mark the places where the XML snippets should be transcluded (references) add elements with the content:ref attribute to the body of the document. The content:ref attribute should contain the name of the resource that you want to include at this point. Which element you use depends on
the circumstances. For purposes of validation you should use an element which is permitted at the location of the reference.
In most cases you may want to use an empty generic wrapper element, such as phrase in DocBook.
The namespace URI for the content:ref attribute is http://stanleysecurity.github.io/PACBook/ns/transclusion.
When the stylesheet is run, it parses the document and finds any element with the content:ref attribute. When it does so, it finds the nearest ancestor element which contains an extended link element with the specified
transclusion role URI, which in turn contains an XLink resource whose xl:label attribute matches the content:ref attribute. The stylesheet keeps the reference element, but replaces the content of the element with the content of the XLink
resource.
You should run this stylesheet after initial large scale, context-free transclusion. If any of your translation strings contain transclusion references, you may need to run this stylesheet after translation instead.
Small scale, inline transclusion can have linguistic consequences. See Linguistic Processing for details of the mechanism that PACBook attempts to deal with these problems.
In order to avoid the problem of duplicate IDs, transclusion resources simply should not contain XML IDs. You could use a schematron rule to enforce this.
It is the responsibility of the author to ensure that the content of the transclusion resources is valid in all the locations where it is transcluded. You may want to validate the document after parametrised transclusion is complete.
DocBook 5.0 does not have XLink resource elements. For this purpose, PACBook provides a custom layer for the DocBook 5.0 schema
which adds a resource element to the extendedlink element. (In DocBook 5.1 it may be possible to use a link element with the xl:type='resource' attribute, but this has not been tested.) The PACBook schema also adds the content:ref attribute to the common attributes. See the PACBook RNG schema.
Extended links are overloaded in PACBook. Perhaps find some other markup for parametrised transclusion definitions, e.g. DoCO or the Document Structural Patterns Ontology.
|
|