Validation and profiling

Validation and profiling
	Chapter 26. Profiling (conditional text)

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 phrase elements.
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 id or xml:id attributes in a document. If you need to put an id or 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.


Customization and profiling		Custom profiling attribute