• VersionSpecificDocs

Marking Up Version-Specific Documentation in DocBook

Rationale

• 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.

The Approach

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>

Important Guidelines

Inconditional Validity

The document must be well-formed and valid with any combination of inclusion/omission of the conditional parts. The document is first validated as a whole, without excluding any of the conditional part. For example, let's suppose that the installation chapter is enclosed into a sect1 element and has its own file. If you want to add another installation chapter for a newer version, you cannot place it after the first one in the same file, since the file will have two top-level element then and will not be well-formed anymore. The solution is to place this new chapter into another file. In any case, the whole document will be assembleed first from the different chapters and for the printed edition, some of the conditional parts will be dropped after that, so you will still get a valid document.

In short, make sure the document is valid as-is and consider if it will still be valid by dropping any of the conditional elements.

Be Explicit in the Text

Since the online version will contain both versions, the text chunks must explicitly express what version do they refer to, since the markup is not present in the rendered document. 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>

It will render as:

To do foobar, type bar.

To do foobar, type baz.

Which makes no sense without the additional version-specific information. Instead of this, do:

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

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

Consistent Version Attributes

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.

Suppose Most Recent Information for the Latest Major Release

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:

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

<para os="freebsd9">To do foobar on &os; 9.X and above, type baz.</para>

In this case, the section marked as 9.X-specific is not strictly 9.X-specific but the markup will help later to find and readjust this part when 8.X or 9.X reaches EOL.

Further Information

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

CategoryStale