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