1 <?xml version='1.0' encoding='UTF-8'?>
\r
2 <chapter xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude"
\r
3 xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:id="conditional">
\r
4 <title>Conditional Text</title>
\r
5 <section xml:id="ConditionalWriting">
\r
6 <title>Writing with Conditional Text</title>
\r
8 <title>Overview</title>
\r
9 <para>The guidelines on using conditional text are based on the <emphasis>Profiling</emphasis>
\r
10 chapter from <link xl:href="http://www.sagehill.net/docbookxsl/index.html">DocBook XSL: The
\r
11 Complete Guide</link>, by Bob Stayton. The current chapter does not describe all of the
\r
12 features supported by DocBook XSL. In particular, this chapter discusses profiling using
\r
13 only the <tag class="attribute">condition</tag> attribute, whereas the <emphasis>DocBook
\r
14 XSL</emphasis> book also describes how to support profiling using other DocBook
\r
18 <title>Conditionalizing elements</title>
\r
19 <para>To conditionalize an element, set the element's <tag class="attribute">condition</tag>
\r
20 attribute to the name of the condition you want to apply. For example, to conditionalize a
\r
21 text block with the <code>fuse</code> condition:</para>
\r
22 <programlisting><simplesect condition="fuse">
\r
24 </simplesect></programlisting>
\r
25 <para>When you conditionalize an element, the condition is applied to <emphasis>all of the
\r
26 enclosed text and every sub-element</emphasis> of the conditionalized element. This
\r
27 mechanism is flexible, because every element in DocBook supports the <tag class="attribute"
\r
28 >condition</tag> attribute. For example, you can conditionalize an entire <tag
\r
29 class="element">chapter</tag>, a <tag class="element">section</tag>, a <tag
\r
30 class="element">figure</tag>, an <tag class="element">example</tag>, or even an individual
\r
31 <tag class="element">code</tag> element.</para>
\r
34 <title>Conditionalizing free-standing text</title>
\r
35 <para>There is one special case not covered by the mechanism for conditionalizing elements.
\r
36 What do you do, if you want to conditionalize a fragment of text that does not correspond to
\r
37 an element? For example, you might want to conditionalize a sentence within a paragraph. In
\r
38 this case, you can use the <tag class="element">phrase</tag> element to enclose the text
\r
39 fragment and then apply the requisite condition to the <tag class="element">phrase</tag>
\r
41 <para>The following example shows how to conditionalize a sentence so that it appears only in
\r
42 the Artix version of the book:</para>
\r
43 <programlisting><para>&prodname; supports a multitude of integration options.
\r
44 <phrase condition="artix">In particular, you can optionally plug in a mainframe integration kit</phrase>
\r
45 </para></programlisting>
\r
48 <title>Conditionalizing comments</title>
\r
49 <para>You can also use conditional text to manage draft comments in a book. These are the kind
\r
50 of comments that you would like to make visible in a draft copy of the output: for example,
\r
51 reminders to self and directions to the reviewer. It is recommended that you insert comments
\r
52 using the remark element with the <code>comment</code> condition applied. For
\r
54 <programlisting><remark condition="comment">REVISIT - Your comment here!</remark></programlisting>
\r
55 <para>To simplify entering comments, the Evergreen template for the Oxygen editor includes a
\r
56 custom option, <guimenuitem>DocBook4 | Insert Comment</guimenuitem>, which automatically
\r
57 inserts a conditionalized <tag class="element">remark</tag> element.</para>
\r
60 <title>Applying multiple conditions</title>
\r
61 <para>If required, you can apply multiple conditions to a single element, using the semicolon,
\r
62 <literal>;</literal>, as the separator character. For example, to apply both the
\r
63 <code>unix</code> and <code>win</code> conditions to a <tag class="element"
\r
64 >simplesect</tag> element, set the <tag class="attribute">condition</tag> attribute as
\r
66 <programlisting><simplesect condition="unix;win"> ... </simplesect></programlisting>
\r
67 <para>Semantically, the effect of setting both of these conditions is that, at build time, the
\r
68 <tag class="element">simplesect</tag> element will be included in the output if either the
\r
69 <code>unix</code> condition OR the <code>win</code> condition is enabled.</para>
\r
72 <section xml:id="ConditionalBuilding">
\r
73 <title>Building Books with Conditional Text</title>
\r
75 <title>Overview</title>
\r
76 <para>When building a book with conditional text, you need to use a special Ant build file to
\r
77 produce the output. The targets of the conditional build file are the same as a regular
\r
78 build file, but the process for generating the output is slightly different. When building a
\r
79 conditional book, the build system first generates an intermediate file,
\r
80 <filename><replaceable>bookname</replaceable>.prfl</filename>, which contains a version
\r
81 of the <filename><replaceable>bookname</replaceable>.xml</filename> book where all of the
\r
82 conditions have been applied. The
\r
83 <filename><replaceable>bookname</replaceable>.prfl</filename> file is then used as the
\r
84 input for the next stage of book building, using the regular templates for HTML and
\r
88 <title>Steps for building with conditions</title>
\r
89 <para>To build a book with conditions, perform the following steps:</para>
\r
92 <para><xref linkend="ConditionalBuildingGet"/></para>
\r
95 <para><xref linkend="ConditionalBuildingSet"/></para>
\r
98 <para><xref linkend="ConditionalBuildingBuild"/></para>
\r
102 <simplesect xml:id="ConditionalBuildingGet">
\r
103 <title>Get the conditional build.xml file</title>
\r
104 <para>To build a book with conditional text, use the conditional version of the Ant
\r
105 <filename>build.xml</filename> file. In the <filename>docs_tools</filename> SVN
\r
106 repository, look for the following file:
\r
107 <filename>trunk/docbook-output/dcbk/custom/build_book_with_conditions.xml</filename></para>
\r
108 <para>Copy this build file into your book directory and rename it to
\r
109 <filename>build.xml</filename>.</para>
\r
111 <simplesect xml:id="ConditionalBuildingSet">
\r
112 <title>Set conditions in build.xml</title>
\r
113 <para>In addition to the usual book properties that you must set in a
\r
114 <filename>build.xml</filename> file (that is, <code>ROOT</code>, <code>DOCID</code>, and
\r
115 <code>LOGO</code>), you must also set a <code>CONDITIONS</code> property that lists the
\r
116 conditions you want to enable. If you want to enable multiple conditions, separate them
\r
117 using a semicolon character, for example:</para>
\r
118 <programlisting> <property name="CONDITIONS" value="condition1;condition2" /></programlisting>
\r
119 <para>This setting would ensure that any conditions marked with <code>condition1</code> AND
\r
120 any conditions marked with <code>condition2</code> are included in the output. In other
\r
121 words, the more conditions you specify here, the more output text you might get.</para>
\r
123 <simplesect xml:id="ConditionalBuildingBuild">
\r
124 <title>Build the book</title>
\r
125 <para>The conditional <filename>build.xml</filename> file supports the same Ant targets for
\r
126 building a book as the normal <filename>build.xml</filename> file. For example, to build
\r
127 both the HTML and PDF output, you can execute Ant with the default target, as
\r
129 <programlisting>> ant</programlisting>
\r
130 <para>The build file also supports the <code>db</code>, <code>pdf</code>, and
\r
131 <code>html</code> Ant targets. In the course of generating the document output, the build
\r
132 file produces an intermediate file,
\r
133 <filename><replaceable>bookname</replaceable>.prfl</filename>, which is a DocBook XML file
\r
134 to which the conditions have been applied.</para>
\r
137 <title>Example</title>
\r
138 <para><xref linkend="ConditionalBuildingExSSCBF"/> shows the top of the
\r
139 <filename>build.xml</filename> file for the FUSE Mediation Router Programmer's Guide,
\r
140 including conditional settings. This book is shared between the FUSE and Artix product.
\r
141 FUSE-specific parts of the book are marked with the condition, <code>fuse</code>, and
\r
142 Artix-specific parts of the book are marked, <code>artix</code>. <xref
\r
143 linkend="ConditionalBuildingExSSCBF"/> shows the settings for building the FUSE version of
\r
144 the book in draft format.</para>
\r
145 <example xml:id="ConditionalBuildingExSSCBF">
\r
146 <title>Sample Settings in a Conditional build.xml File</title>
\r
147 <programlisting><?xml version="1.0" encoding="UTF-8"?>
\r
148 <project name="MRGettingStarted" default="all" basedir=".">
\r
149 <property environment="env" />
\r
150 <!-- Choose one of the following common build files to import:
\r
151 build_artix_common.xml (Artix)
\r
152 build_fuse_common.xml (FUSE)
\r
154 <import file="${env.DBCK_HOME}/lib/build_fuse_common.xml"/>
\r
156 <!-- Edit the following properties for your book: -->
\r
157 <property name="ROOT" value="prog_guide" />
\r
158 <property name="DOCID" value="FuseMRProg" />
\r
159 <property name="LOGO" value="fmr" />
\r
160 <property name="CONDITIONS" value="fuse;comment" />
\r
162 <!-- DO NOT MODIFY ANYTHING BELOW THIS LINE -->
\r
163 ...</programlisting>
\r
165 <para>Where the <code>CONDITIONS</code> property specifies two conditions: <code>fuse</code>
\r
166 and <code>comment</code>. This build file processes the conditions as follows:</para>
\r
169 <para>Unmarked elements not enclosed by conditionalized elements are included in the
\r
173 <para>Elements marked with the <code>artix</code> condition are
\r
174 <emphasis>excluded</emphasis> from the output.</para>
\r
177 <para>Elements marked with the <code>fuse</code> condition are
\r
178 <emphasis>included</emphasis> in the output.</para>
\r
181 <para>Elements marked with the <code>comment</code> condition are
\r
182 <emphasis>included</emphasis> in the output.</para>
\r
187 <title>Managing comments</title>
\r
188 <para>Unlike other conditions, which typically remain unchanged for a long time, the
\r
189 <code>comment</code> condition changes relatively frequently, as you switch between
\r
190 producing draft copies and release copies. It is something that you need to keep in mind,
\r
191 when building a release, that you need to disable the <code>comment</code> condition before
\r
192 building the output.</para>
\r
195 <title>Building without conditions</title>
\r
196 <para>It is not possible to build a book with a blank <code>CONDITIONS</code> property. If you
\r
197 want to build a book without conditions, you could either replace the conditional
\r
198 <filename>build.xml</filename> file with a regular <filename>build.xml</filename> file or
\r
199 you could enable every condition in the <code>CONDITIONS</code> property (thereby ensuring
\r
200 that the complete source is processed).</para>
\r