6 Modularizing Documentation Projects #

Instead of putting the contents of a complete article or book into the MAIN file, DocBook allows you to divide the text into separate document files. They are then assembled in the MAIN file using XIncludes as shown in Example 2.9, “MAIN file of a Set (DocBook 4.x)”. XIncludes can be used for splitting up sets, books, articles or chapters into separate files. For more information, refer to Physical Divisions: Breaking a Document into Separate Files (http://www.docbook.org/tdg51/en/html/ch02.html).

XIncludes are fully supported and do not cause any problems with DAPS. For example, daps commands like linkcheck or spellcheck also follow XIncludes.

When maintaining a large number of documents for a product, it can be difficult to keep a consistent set of entities if these entities are declared in the document type declarations of individual XML files. For large documentation projects, it is therefore useful to put all entity declarations into a separate file and reference that file in the individual XML files.

<?xml version="1.0" encoding="iso-8859-1" ?>
<!ENTITY exampleuser "tux">
<!ENTITY exampleuserII "wilber">
<!ENTITY examplegroup "users">
[...]

<?xml version="1.0"?>
<!DOCTYPE chapter PUBLIC [...]
[
  <!ENTITY % entities SYSTEM "entity-decl.ent"> 1
  %entities; 2
]>
<chapter>
<title>Managing User Accounts</title>
[...]

For more information, refer to Modular DocBook Files: Shared text entities (http://www.sagehill.net/docbookxsl/ModularDoc.html).

Separate entity files do not cause any problems with DAPS— during generation of output, the entities will be treated equally to entities declared in individual XML files.

It is also possible to use multiple entity files by including them into the separate entity file that is referenced in the XML file.

<?xml version="1.0" encoding="iso-8859-1" ?>
<!ENTITY exampleuser "tux">
<!ENTITY exampleuserII "wilber">
<!ENTITY examplegroup "users">
[...]
<!ENTITY % network-entities SYSTEM "network-decl.ent"> 1
%network-entities; 2
<!ENTITY % more-entities SYSTEM "another-decl.ent"> 1
%more-entities; 2

Similar products often share a considerable amount of features and differ in details only. It is therefore convenient to apply the same approach to the documentation of similar products or product families: Share most of the XML source code and only differentiate text snippets where necessary. DocBook allows you to create documentation variants from the same pool of XML sources by means of profiling.

In DocBook XML files you can mark some elements as conditional by using profiling attributes. When processing the files to generate output, specify which conditions apply to the output. The stylesheets will then include or exclude the marked text, according to the conditions.

Profiling allows you to keep both common and product-specific content in one XML file and select at production time which information to include in the output.

<simplelist>
  <member>Common Feature 1</member>
  <member>Common Feature 2</member>
  <member>Common Feature 3</member>
  <member condition="basic">Basic Feature 1</member>
  <member condition="prof">Professional Feature 1</member>
  <member condition="prof">Professional Feature 2</member>
</simplelist>

<simplelist>
  <member>Common Feature 1</member>
  <member>Common Feature 2</member>
  <member>Common Feature 3</member>
  <member condition="basic">Basic Feature 1</member>
  <member condition="prof">Professional Feature 1</member>
  <member condition="prof">Professional Feature 2</member>
  <member condition="prof" vendor="oemcompany">OEM Feature 1</member>
</simplelist>

6.3.2 Using Profiling with DAPS #

To create multiple documentation variants of the same pool of DocBook files with DAPS, the following requirements need to be fulfilled:

1. XML Files: Profiling Attributes

2. MAIN File: Processing Instruction

3. DC Files: Profiling Parameters

For a comprehensive example showing all requirements in detail, refer to Section 6.3.2.4, “Profiling Example”.

6.3.2.1 XML Files: Profiling Attributes #

In DAPS, each profiling attribute has a corresponding profiling parameter to be used in the DC file, see Section 6.3.2.3, “DC Files: Profiling Parameters”. The profiling parameters define which profiling attributes and values to interpret during generation of output.

The names of the profiling parameters are derived from the profiling attributes, but written in uppercase letters and preceded by the prefix PROF.

Table 6.4: Profiling Attributes (DocBook) and Profiling Parameters (DAPS) #

Attribute Name	Use	Profiling Parameter
arch	Computer or chip architecture, such as i386.	PROFARCH
audience	Intended audience of the content, such as instructor. Added in DocBook version 5.0.	PROFAUDIENCE
condition	No preassigned semantics, general purpose attribute.	PROFCONDITION
conformance	Conformance to standards, as for example lsb (Linux Standards Base).	PROFCONFORMANCE
lang	Language code, such as de_DE.	PROFLANG
os	Operating system.	PROFOS
outputformat	Output format to which the element applies (for example, print or EPUB). Only available for DocBook 5.1 or later.	PROFOUTPUTFORMAT
revision	Editorial revision, such as v2.1.	PROFREVISION
revisionflag	Revision status of the element, such as changed. This attribute has a fixed set of values to choose from.	PROFREVISIONFLAG
role	General purpose attribute, with no preassigned semantics. As the role attribute is not solely “reserved” for profiling but can be used for other purposes in a document, we would recommend to not use this for profiling. For further details, see http://sagehill.net/docbookxsl/ProfilingWithRole.html.	PROFROLE
security	Security level, such as high.	PROFSECURITY
status	Editorial or publication status, such as InDevelopment or draft.	PROFSTATUS
userlevel	Level of user experience, such as beginner.	PROFUSERLEVEL
vendor	Product vendor.	PROFVENDOR
wordsize	Word size (width in bits) of the computer architecture, such as 64bit. Added in DocBook version 4.4.	PROFWORDSIZE

6.3.2.2 MAIN File: Processing Instruction #

To activate generation of profiled output in DAPS, the following processing instruction (PI) must be included in the header of the MAIN file, before the root element.

Note: Adjusting the DocBook Version in the PI

As the profiling PI includes the DocBook version number, it needs to be adjusted according to the DocBook version you use. See Example 6.6, “Profiling PI in a DocBook 4.5 File” and Example 6.7, “Profiling PI in a DocBook 5.0 File”.

Example 6.6: Profiling PI in a DocBook 4.5 File #

<?xml-stylesheet
  href="urn:x-daps:xslt:profiling:docbook45-profile.xsl"
  type="text/xml" ?>

Example 6.7: Profiling PI in a DocBook 5.0 File #

<?xml-stylesheet
  href="urn:x-daps:xslt:profiling:docbook50-profile.xsl"
  type="text/xml" ?>

The MAIN file of a documentation project is referenced by the MAIN parameter in the DC file. If the processing instruction is missing in the MAIN file, any profiling parameters in the DC file will be ignored during generation of the output.

Tip: Include PI in All XML Files

Although DAPS only checks for the profiling PI in the MAIN file, it is a good idea to include the PI in all XML files for any projects that need profiling. Otherwise you might forget to move the PI to the respective MAIN file in case of restructuring the XML sources. Having the PI in all XML files does not hurt: Generation of profiled output is only triggered if your DC files contain profiling parameters.

6.3.2.3 DC Files: Profiling Parameters #

Depending on the profiling attributes used in your XML files, a DC file may contain multiple profiling parameters, see Table 6.4, “Profiling Attributes (DocBook) and Profiling Parameters (DAPS)”. Profiling parameters define which of the profiling attributes should be interpreted by DAPS when generating output. For each profiling parameter, set the respective attribute values for which you want to filter during the profiling process. The spelling of the values must be the same that is used in the XML files.

6.3.2.4 Profiling Example #

In the following, find a comprehensive example that shows the basic DAPS profiling requirements in more detail. It is based on the examples in Section 6.3.1, “Introduction to DocBook Profiling” about the fictional software Frog Sound Recordings. The software is available in a basic edition, a professional edition and a professional OEM edition, shipped by an OEM vendor. The following example shows all files that you need to consider (XML files, MAIN file, and DC file).

Example 6.8: XML File With Profiling Attributes (DocBook 4.x) #

<?xml version="1.0" encoding="utf-8"?>
[...]

<chapter id="frog.features">
 [...]
 <simplelist>
   <member>Common Feature 1</member> 1
   <member>Common Feature 2</member> 1
   <member>Common Feature 3</member> 1
   <member condition="basic">Basic Feature 1</member> 2
   <member condition="prof">Professional Feature 1</member> 3
   <member condition="prof">Professional Feature 2</member> 3
   <member condition="prof" vendor="oemcompany">OEM Feature 1</member> 4
 </simplelist>
 [...]
</chapter>

1	Unprofiled list items. The common features 1-3 are available in all software editions or versions.
2	List item profiled with attribute condition and attribute value basic. Basic Feature 1 is only available in the basic software edition for home users.
3	List item profiled with attribute condition and attribute value prof. Professional Feature 1 and Professional Feature 2 are only available in the professional software edition for enterprise customers.
4	List item profiled with two attributes: Attribute condition with attribute value prof and attribute vendor with attribute value oemcompany. OEM Feature 1 is only available in the professional OEM software edition for enterprise customers.

Example 6.9: MAIN file With PI for Profiling (DocBook 4.5) #

<?xml version="1.0" encoding="utf-8"?>
<?xml-stylesheet
 href="urn:x-daps:xslt:profiling:docbook45-profile.xsl"
 type="text/xml"
 title="Profiling step"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
                         "http://www.docbook.org/xml/4.5/docbookx.dtd"
[<!ENTITY % entities SYSTEM "entity-decl.ent">
%entities;
]>

<!--the following article is contained in the file art_frog.xml-->

<article lang="en" id="art.frog">
 <title>Frog Sound Recordings</title>
 <subtitle>Product Description</subtitle>
 [...]
</article>

If the processing instruction (PI) is missing, any profiling parameters in the DC file will be ignored.

Example 6.10: MAIN file With PI for Profiling (DocBook 5.0) #

<?xml version="1.0" encoding="utf-8"?>
<?xml-stylesheet
 href="urn:x-daps:xslt:profiling:docbook50-profile.xsl"
 type="text/xml"
 title="Profiling step"?>
<!DOCTYPE article
[<!ENTITY % entities SYSTEM "entity-decl.ent">
%entities;
]>

<!--the following article is contained in the file art_frog.xml-->

<article xml:lang="en" xml:id="art.frog"
   xmlns="http://docbook.org/ns/docbook">
 <title>Frog Sound Recordings</title>
 <subtitle>Product Description</subtitle>
 [...]
</article>

If the processing instruction (PI) is missing, any profiling parameters in the DC file will be ignored.

Use the PI <?xml-stylesheet href="urn:x-daps:xslt:profiling:docbook51-profile.xsl" type="text/xml" title="Profiling step"> for DocBook version 5.1.

Example 6.11: DC File with Profiling for Home Edition #

## Doc Config File for Frog Sound Recordings
## (Home Edition)

## Mandatory Parameters
MAIN="art_frog.xml" 1

## Profiling
PROFCONDITION="basic" 2
[...]

1	MAIN parameter referencing the MAIN file. See Example 6.9 (DocBook 4) or Example 6.10 (DocBook 5).
2	DAPS profiling parameter for the condition profiling attribute. It defines that XML elements tagged with condition="basic" are included in the output.

Example 6.12: DC File with Profiling for Professional Edition #

## Doc Config File for Frog Sound Recordings
## (Professional Edition)

## Mandatory Parameters
MAIN="art_frog.xml" 1

## Profiling
PROFCONDITION="prof" 2
[...]

1	MAIN parameter referencing the MAIN file. See Example 6.9 (DocBook 4) or Example 6.10 (DocBook 5).
2	DAPS profiling parameter for the condition profiling attribute. It defines that XML elements tagged with condition="prof" are included in the output.

Example 6.13: DC File with Profiling for Professional Edition (OEM Version) #

## Doc Config File for Frog Sound Recordings
## (Professional Edition, OEM Version)

## Mandatory Parameters
MAIN="art_frog.xml" 1

## Profiling
PROFCONDITION="prof" 2
PROFVENDOR="oemcompany" 3
[...]

1	MAIN parameter referencing the MAIN file. See Example 6.9, “MAIN file With PI for Profiling (DocBook 4.5)” or Example 6.10, “MAIN file With PI for Profiling (DocBook 5.0)” .
2	DAPS profiling parameter for the condition profiling attribute. It defines that XML elements tagged with condition="prof" are included in the output.
3	DAPS profiling parameter for the vendor profiling attribute. It defines that XML elements tagged with vendor="oemcompany" are included in the output.

For maximum flexibility in generating documentation variants from the same source, DAPS also supports the combination of entities and profiling. As you already learned in Section 6.2, “Declaring Entities in a Separate File”, it is useful for modularization purposes to declare entities in a separate file and to re-use it in multiple documentation projects.

For multiple use of entities like &productname; or &productnumber;, declare them in a separate file and add profiling within the entities as shown in Example 6.14. During generation of output, DAPS then automatically replaces the entities with different values during output, depending on the context.

<!--the following declarations are contained in the file entity-decl.ent -->

<!ENTITY productname
 '<phrase cond="basic">Frog Sound Recordings (Basic)</phrase>
  <phrase cond="prof">Frog Sound Recordings (Professional)</phrase>
  <phrase cond="prof" vendor="oemcompany">Gecko Sound Recordings (Professional)</phrase>'>

<!ENTITY productnumber
 '<phrase cond="basic">1.0</phrase>
  <phrase cond="prof">4.2</phrase>
  <phrase cond="prof" vendor="oemcompany">4.21</phrase>'>

Now that you have “introduced” the entities for each document, use the entities in the text wherever you need them.

<?xml version="1.0" encoding="utf-8"?>

<?xml-stylesheet
 href="urn:x-daps:xslt:profiling:docbook45-profile.xsl"
 type="text/xml"
 title="Profiling step"?> 1

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
                         "http://www.docbook.org/xml/4.5/docbookx.dtd"
[<!ENTITY % entities SYSTEM "entity-decl.ent">
%entities;
 ]> 2

<!--the following article is contained in the file art_frog.xml-->

<article lang="en" id="art.frog">
 <title>Frog Sound Recordings</title>
 <subtitle>Product Description</subtitle>
  <articleinfo> 3
   <productname>&productname;</productname> 4
   <productnumber>&productnumber;</productnumber> 5
 </articleinfo>
  <abstract>
   <para>
    &productname; &productnumber; is a software for recording, editing, 6
    and mixing audio data.
   </para>
  </abstract>
 [...]
</article>

<?xml version="1.0" encoding="utf-8"?>

<?xml-stylesheet
 href="urn:x-daps:xslt:profiling:docbook50-profile.xsl"
 type="text/xml"
 title="Profiling step"?> 1

<!DOCTYPE article
[<!ENTITY % entities SYSTEM "entity-decl.ent">
%entities;
]> 2

<!--the following article is contained in the file art_frog.xml-->

<article xml:lang="en" xml:id="art.frog"
   xmlns="http://docbook.org/ns/docbook">
 <title>Frog Sound Recordings</title>
 <subtitle>Product Description</subtitle>
  <info> 3
   <productname>&productname;</productname> 4
   <productnumber>&productnumber;</productnumber> 5
 </info>
  <abstract>
   <para>
    &productname; &productnumber; is a software for recording, editing, 6
    and mixing audio data.
   </para>
  </abstract>
 [...]
</article>

In any output format, the entities (4, 5, 6) will automatically be replaced with different values. The actual values depend on the profiling parameters contained in the DC file that you use for generating the output. For an example, refer to Table 6.5. It shows output variants that can be generated from the XML code in Example 6.15 or Example 6.16 plus the entity declaration in Example 6.14 by using different DC files.