Marking Up Version-Specific Documentation in DocBook

• Outdated information is usually forgotten; markup can also help cleaning these up later
• The printed edition of Handbook will focus on 9.X, leaving out parts that are specific to older releases, so somehow we need to distinguish these parts.

DocBook provides a way (called profiling) of marking up conditional text. This is done with XML attributes. There are predefined profiling attributes or it is also possible to use a schema extension and define further profiling attributes. In our case, the os attribute will do.

This example shows how to mark up a whole version-specific section:

<sect2 os="freebsd8">
  <title>Doing Foobar on FreeBSD 8.X</title>
  ...
</sect2>

<sect2 os="freebsd9">
  <title>Doing Foobar on FreeBSD 9.X</title>
  ...
</sect2>

It is also possible to mark up smaller fragments:

<para os="freebsd8">To do foobar on FreeBSD 8.X, type bar.</para>

<para os="freebsd9">To do foobar on FreeBSD 9.X, type baz.</para>

• The document must be well-formed and valid with any combination of inclusion/omission of the conditional parts. The printed version will only contain one option and the online version will contain both so both versions must build.
• Since the online version will contain both versions, the text chunks must explicitly express what version do they refer to, even if the markup is present. Consequently, the following example is not acceptable:

<para os="freebsd8">To do foobar, type bar.</para>

<para os="freebsd9">To do foobar, type baz.</para>

For further information, please consult the following link: http://www.sagehill.net/docbookxsl/Profiling.html