If you use profiling, you will want to make sure that your documents are valid both before and after the profiling step. You will want them to be valid before profiling so that you can use a validating authoring tool to help you write the files. And the profiled versions should also be valid because the DocBook XSL stylesheets assume the document being processed is valid DocBook. You may get strange results if it is not valid. The profiling step could make a valid document invalid, and most XSLT processors do not take the time to validate the input XML.
Here are some of the areas to watch out for:
When you add a profiling attribute to an element, consider whether the document will still be valid if the element is deselected during profiling. Even if it is valid, make sure the document will still make sense if it is profiled out.
do not try to use multiple
title elements at the same location. The DTD permits only a single
title in any element. Instead, use multiple
phrase elements within the single
title element, and put the profiling attributes on the
Alternatively, you could exploit the fact that DocBook info elements such as
chapterinfo permit multiple
title elements. You could put multiple profiled titles inside the element's info element. In either case, make sure only one of the titles is selected during processing.
You cannot have duplicate
xml:id attributes in a document. If you need to put an
xml:id on a chapter, section, or figure for cross referencing, then you cannot have multiple versions of that element with the same id value. You'll have to create a single element with the id and make the content of the element conditional. It helps if only part of the content needs to be conditional.
Nesting conditional elements adds significant complexity to your document. You have to consider each combination of profiling values to see if it will be valid and make sense.
To ensure that your profiled documents are valid, you might want to apply the profiling-only stylesheet described in the section “Two-pass processing”. You will want to perform just the first step to generate the profiled DocBook document, and then run a DTD validation check on that temporary document. However, by default the profiled output does not include a DOCTYPE declaration, and so a validator does not know what DTD to validate the document against.
To validate a profiled document, you could use
xmllint with the
--dtdvalid option, which can apply an external DTD that is designated on the command line. The
xmllint program is included in the
libxml2 distribution necessary for xsltproc. For example:
xmllint --dtdvalid /path/to/docbookx.dtd --noout myfile.xml
You could also create a customization layer for the profiling stylesheet which inserts a DOCTYPE declaration in the profiled output. The
xsl:output element lets you specify both the PUBLIC and SYSTEM identifiers for a DOCTYPE. The profiling stylesheet does not do that by default because it does not know what version of the DTD you want to validate against. The following customization layer will generate a DOCTYPE for version 4.5 of the DocBook DTD:
<?xml version="1.0"?> <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version='1.0'> <xsl:import href="../docbook-xsl/profiling/profile.xsl"/> <xsl:output method="xml" doctype-public="-//OASIS//DTD DocBook XML V4.5//EN" doctype-system="http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"/> </xsl:stylesheet>
This will result in a profiled document that includes a DOCTYPE:
<?xml version="1.0"?> <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> <book> ...
With this DOCTYPE in place, you can validate the profiled output against the standard DocBook DTD.
|DocBook XSL: The Complete Guide - 4th Edition||PDF version available|
Copyright © 2002-2007 Sagehill Enterprises