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.
Don't 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
attributes in a document. If you need to put an id on a chapter, section, or figure for cross referencing, then you can't have multiple versions of that element with the same id. 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”. Perform just the first step to generate the profiled DocBook document, and then run a DTD validation check on that temporary document.
DocBook XSL: The Complete Guide - 3rd Edition | PDF version available | Copyright © 2002-2005 Sagehill Enterprises |