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>

• The attribute values have the form freebsdX, where X is the major version they apply to. At this point, minor versions are not distinguished at the level of the markup but may be distinguished in the actual text. For example, if a new feature was introduced in FreeBSD 8.2, that shall still fall into a freebsd8 section.
• If not mentioned explicitly, the most recent information applies to newer releases, as well. For example, if there are freebsd8 and freebsd9 sections on doing foobar, it is supposed that the freebsd9 section also applies to FreeBSD 10.0 even if there is no explicit freebsd10 section. This may be clarified in the text by writing “To do foobar on FreeBSD 9.0 and above, do …” instead of “To do foobar on FreeBSD 9.0, do …”.

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