The Crash Course to DocBook

4.4. Using Marked Sections to Handle Conditional Content

Note

This is quite advanced technology. Feel free to skip it if you want to be told about more basic topics.

Please be aware that marked sections are not supported by XML. Skip this section too if you are using XML.

Sometimes you need to have different versions of the content for different purposes. There are several ways to do this using SGML, one of which is called marked sections. A simple example of conditional content might be the description of keys used in a software program where they appear in boxes in the printed manual but are blue inside brackets on the web site or CD. Rather than have two separate versions of the conventions for each output of the manual, you can use marked sections to keep both variations in the same document.

There are different types of marked sections, but the types that allow you to control conditional content are ignore/include sections. These markers act like on/off switches to allow content to be included or ignored in different situations.

The marker for an include marked section looks like this:


<![INCLUDE [ keys are boxed, such as <key>F1</key> ]]>

while an ignore marked section looks like this:


<![IGNORE [ keys are blue inside brackets, such as <key>F1</key> ]]>

INCLUDE and IGNORE are the keywords that tell the SGML system what to include or skip. As this example shows, marked sections can contain both text and tags as long as the tags within the markers are balanced (if a tag starts inside a marker, then it ends inside the same marker).

In this example, you leave the markers for the print version as INCLUDE and the markers for the electronic version as IGNORE when you print a master copy. When you create the electronic book or HTML for the web site, you change the markers for the print version to IGNORE and the markers for the electronic version to INCLUDE. This works just fine, unless you have several different sections you need to include or ignore together - it's cumbersome to change each one manually and you can easily make a mistake.

So instead, you can define parameter entities under any names you want and then change the entities to turn the include/ignore switches. To do this, you add parameter entity declarations in the internal subset at the top of your master SGML document. For example:


<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.4//EN" [
...
<!ENTITY % hardcopy "INCLUDE">
<!ENTITY % softcopy "IGNORE">
...]>

You then use the names for each marked section, like this:


<![%hardcopy; [ keys are boxed, such as <key>F1</key> ]]>
<![%softcopy; [ keys are blue inside brackets, such as <key>F1</key> ]]>

To print the master copy, you leave the entity declarations as they are shown above. The SGML system interprets each %hardcopy; it finds as INCLUDE and includes those marked sections. The %softcopy; is interpreted as IGNORE and those sections are skipped. When you're ready to produce the electronic version, you only have to change the entity declarations at the top of the file, like this:


<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.4//EN" [
...
<!ENTITY % hardcopy "IGNORE">
<!ENTITY % softcopy "INCLUDE">
...]>

With this single change, the electronic versions are included and the printed versions are skipped.

Marked sections can be simple, but they are not always the best choice to manage conditional text. They are best if you use them sparingly and in very clear situations - it's easy to figure out when to use them and when to change the INCLUDE/IGNORE switches. Some of the problems that they can create include: