Customizing the semantic XML files generated by w2x
Converting custom character styles to semantic tags
Converting a custom character style to an XHTML element (possibly having specific attributes) is simple and does not require writing a XED script. Suffice for that to pass parameter inlines.convert to the Edit step.
Example 1: convert text spans having a “Code” character style to XHTML element code:
-p edit.inlines.convert "c-Code code"
Notice that the name of character style in the generated XHTML+CSS file is always prefixed by “c-“.
The syntax for the value of parameter inlines.convert is:
value → conversion [ S ‘!’ S conversion ]*
conversion → style_spec S XHTML_element_name [ S attribute ]*
style_spec → style_name | style_pattern
style_pattern → ‘/’ pattern ’/’ | ‘^’ pattern ‘$’
attribute → attribute_name ‘=’ quoted_attribute_value
quoted_attribute_value → “’” value “’” | ‘”’ value ‘”’
Example 2: in addition to what’s done in above example 1, convert text spans having a “Abbrev” character style to XHTML element abbr having a title=”???” attribute:
-p edit.inlines.convert "c-Code code ! c-Abbrev abbr title='???'"
What if the semantic XHTML created by the Edit step is then converted to DITA or DocBook by the means of a Transform step?
In the case of XHTML elements code and abbr, there is nothing else to do because the stock XSLT stylesheets already support these elements:
w2x_install_dir/xslt/topic.xslt converts XHTML code to DITA codeph and XHTML abbr to DITA keyword,
w2x_install_dir/xslt/docbook.xslt converts XHTML code to DocBook code and XHTML abbr to DocBook abbrev.
The general case which also requires using custom XSLT stylesheets is explained in section The general case.
Converting custom paragraph styles to semantic tags
Converting a custom paragraph style to an XHTML element (possibly having specific attributes) is simple and does not require writing a XED script. Suffice for that to pass parameter blocks.convert to the Edit step.
Example 1.a: convert paragraphs having a “ProgramListing” paragraph style to XHTML element pre:
-p edit.blocks.convert "p-ProgramListing pre"
Notice that the name of paragraph style in the generated XHTML+CSS file is always prefixed by “p-“.
If you use the above blocks.convert specification, it will work fine, except that you’ll end up with several consecutive pre elements (one pre per line of program listing). This is clearly not what you want. You want consecutive pre elements to be merged into a single pre element. Fortunately implementing this too is quite simple.
Example 1.b: convert paragraphs having a “ProgramListing” paragraph style to XHTML element span (having grouping attributes; more about this below):
-p edit.blocks.convert "p-ProgramListing span g:id='pre' g:container='pre'"
When any of the target XHTML elements have grouping attributes (g:id='pre'7, g:container='pre', in the above example), then w2x_install_dir/xed/blocks.xed automatically invokes the group() command at the end of the conversions. This has the effect of grouping consecutive <span g:id='pre' g:container='pre'> into a common pre parent element.
Given the fact that XED command group() automatically removes grouping attributes when done and that w2x_install_dir/xed/finish.xed discards all useless span elements, this leaves us with clean pre elements containing text8.
The syntax for the value of parameter blocks.convert is:
value → conversion [ S ‘!’ S conversion ]*
conversion → style_spec S XHTML_element_name [ S attribute ]*
style_spec → style_name | style_pattern
style_pattern → ‘/’ pattern ’/’ | ‘^’ pattern ‘$’
attribute → attribute_name ‘=’ quoted_attribute_value
quoted_attribute_value → “’” value “’” | ‘”’ value ‘”’
Example 3: in addition to what’s done in above example 1.b, convert paragraphs having a “Term” paragraph style to XHTML element dt, convert paragraphs having a “Definition” paragraph style to XHTML element dl and group consecutive dt and dl elements into a common dl parent:
-p edit.blocks.convert "p-Term dt g:id='dl' g:container='dl' !¬
p-Definition dd g:id='dl' g:container='dl' !¬
p-ProgramListing span g:id='pre' g:container='pre'"
What if the semantic XHTML created by the Edit step is then converted to DITA or DocBook by the means of a Transform step?
In the case of XHTML elements pre, dt, dd and dl, there is nothing else to do because the stock XSLT stylesheets already support these elements.
The general case which also requires using custom XSLT stylesheets is explained in section The general case.
The general case
In the general case, customizing the semantic XML files generated by w2x requires writing both a XED script and an XSLT stylesheet.
For example, let’s suppose we want to group all the paragraphs having a “Note” paragraph style and to generate for such groups DocBook and DITA note elements.
The following blocks.convert parameter would allow to very easily create the desired groups:
-p edit.blocks.convert "p-Note p g:id='note_group_member'¬
g:container='div class=\”role-note\” ’"
However this would leave us with two unsolved problems:
A paragraph having a “Note” paragraph style often starts with bold text “Note:”. We want to eliminate this redundant label.
The stock XSLT stylesheets will not convert XHTML element <div class=”role-note”> to a DocBook or DITA note element.
A custom XED script
The first problem is solved by the following w2x_install_dir/doc/manual/customize/notes.xed script:
namespace "http://www.w3.org/1999/xhtml";
namespace html = "http://www.w3.org/1999/xhtml";
namespace g = "urn:x-mlmind:namespace:group";
for-each /html/body//p[get-class("p-Note")] {
delete-text("note:\s*", "i");
if content-type() <= 1 and not(@id) {
delete();
} else {
remove-class("p-Note");
set-attribute("g:id", "note_group_member");
set-attribute("g:container", "div class='role-note'");
}
}
group();
The “Note:” label, if any, is deleted using XED command delete-text. If doing this creates a useless empty (content-type() <= 1) paragraph, then delete this paragraph using XED command delete.
The above script is executed after stock script w2x_install_dir/xed/blocks.xed by the means of the following w2x command-line option:
-pu edit.after.blocks customize\notes.xed
A custom XSLT stylesheet
The second problem is solved by the following w2x_install_dir/doc/manual/customize/custom_topic.xslt XSLT 1.0 stylesheet:
<xsl:stylesheet version="1.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:h="http://www.w3.org/1999/xhtml"
exclude-result-prefixes="h">
<xsl:import href="w2x:xslt/topic.xslt"/>
<xsl:template match="h:div[@class = 'role-note']">
<note>
<xsl:call-template name="processCommonAttributes"/>
<xsl:apply-templates/>
</note>
</xsl:template>
...
</xsl:stylesheet>
This stylesheet, which imports stock w2x_install_dir/xslt/topic.xslt, is used for the topic, map and bookmap output formats (see –o option). Similar, very simple, stylesheets have been developed for the docbook and docbook5 output formats.
Note: Something like “w2x:xslt/topic.xslt” is an absolute URL supported by w2x. “w2x:” is an URL prefix (defined in the automatic XML catalog used by w2x) which specifies the location of the parent directory of both the xed/ and xslt/ subdirectories.
The above stylesheet replaces the stock one by the means of the following w2x command-line option:
-o topic -t customize\custom_topic.xslt
Do not forget to specify the –t option after the –o option, because it’s the –o option which implicitly invokes stock w2x_install_dir/xslt/topic.xslt (this has been explained in chapter Going further with w2x) and we want to use –t to override the use of the stock XSLT stylesheet.
Tip: You’ll find a template for custom XED scripts and several templates for custom XSLT stylesheets in w2x_install_dir/doc/manual/templates/.
For example, in order to create w2x_install_dir/doc/manual/customize/custom_topic.xslt, we started by copying template XSLT stylesheet w2x_install_dir/doc/manual/templates/template_topic.xslt.
7 Any value would do (e.g. g:id=”foo” would have worked as well). Suffice for consecutive elements to be grouped to all have the same g:id attribute.
8 Unless you specify:
-p edit.prune.preserve "p-ProgramListing"
script w2x_install_dir/xed/prune.xed will cause open lines to be stripped from the generated pre element.