From 9b3949ec8547b290bd14b01ee3a6417b45d04587 Mon Sep 17 00:00:00 2001 From: Norman Walsh Date: Wed, 31 Jan 2024 07:53:44 +0000 Subject: [PATCH] Clarify the semantics of transform-original --- src/guide/xml/ch04.xml | 52 +++++++++++++++++++++++++++++++----------- 1 file changed, 39 insertions(+), 13 deletions(-) diff --git a/src/guide/xml/ch04.xml b/src/guide/xml/ch04.xml index 7069717fd..3dcb7bc16 100644 --- a/src/guide/xml/ch04.xml +++ b/src/guide/xml/ch04.xml @@ -542,7 +542,7 @@ original document is transformed several times before converting it to HTML. The standard transformations are: - + Adjust the logical structure. Adds an XML base attribute to the root of the document and converts media object entityref attributes into fileref attributes. @@ -587,7 +587,7 @@ extension function is available and the stylesheet specifies a relax-ng-grammar. - + Process Oxygen change markup. Only occurs if oxy-markup is true and the document contains Oxygen change markup processing instructions. @@ -596,19 +596,45 @@ Oxygen change markup processing instructions. A customization can introduce transformations to the original -document: before the standard transformations by specifying them in -transform-original; after the standard transformations -but before the transformation to HTML by specifying them in -transform-before; or after the HTML transformation -by specifying them in transform-after. (If you need +document using three parameters: + + + +transform-original + +This transform runs before step in the standard transformations. +If this transformation is used, it must take special care to preserve the +base URI of the original document by adding an xml:base +attribute to the root element (if it doesn’t already have one). +Only the first transformation in the list has access to the original base URI. +If it isn’t preserved, relative references to other documents will be resolved against +the static base URI of the stylesheet and not the URI of the original document. That’s +unlikely to be correct. + + + +transform-before + +This transformation runs after step . Its +input is the DocBook document that will be transformed into HTML. + + + + +transform-after + +This transformation runs after the DocBook document has been transformed into HTML. +The resulting HTML document is not valid HTML, but contains islands of valid HTML that will +be separated out into chunks by subsequent processing. + + + + + +(If you need to insert a transformation in the middle of the standard transformations, you’ll have to update the v:standard-transforms -variable.) - - -Transformations in transform-after will be processing -the HTML result of applying the “main” DocBook transformation. - +variable in your customization.) Each of the transformation variables holds a list of transforms that will be applied in the order specified. Each member of the list can be a map or a