docs/1.6/conditional.xml

   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
   7     <simplesect>\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
  15         attributes.</para>\r
  16     </simplesect>\r
  17     <simplesect>\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>&lt;simplesect condition="fuse">\r
  23     ...\r
  24 &lt;/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
  32     </simplesect>\r
  33     <simplesect>\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
  40         element.</para>\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>&lt;para&gt;&amp;prodname; supports a multitude of integration options.\r
  44 &lt;phrase condition="artix">In particular, you can optionally plug in a mainframe integration kit&lt;/phrase>\r
  45 &lt;/para></programlisting>\r
  46     </simplesect>\r
  47     <simplesect>\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
  53         example:</para>\r
  54       <programlisting>&lt;remark condition="comment">REVISIT - Your comment here!&lt;/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
  58     </simplesect>\r
  59     <simplesect>\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
  65         follows:</para>\r
  66       <programlisting>&lt;simplesect condition="unix;win"> ... &lt;/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
  70     </simplesect>\r
  71   </section>\r
  72   <section xml:id="ConditionalBuilding">\r
  73     <title>Building Books with Conditional Text</title>\r
  74     <simplesect>\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
  85         PDF.</para>\r
  86     </simplesect>\r
  87     <simplesect>\r
  88       <title>Steps for building with conditions</title>\r
  89       <para>To build a book with conditions, perform the following steps:</para>\r
  90       <orderedlist>\r
  91         <listitem>\r
  92           <para><xref linkend="ConditionalBuildingGet"/></para>\r
  93         </listitem>\r
  94         <listitem>\r
  95           <para><xref linkend="ConditionalBuildingSet"/></para>\r
  96         </listitem>\r
  97         <listitem>\r
  98           <para><xref linkend="ConditionalBuildingBuild"/></para>\r
  99         </listitem>\r
 100       </orderedlist>\r
 101     </simplesect>\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
 110     </simplesect>\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>    &lt;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
 122     </simplesect>\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
 128         follows:</para>\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
 135     </simplesect>\r
 136     <simplesect>\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>&lt;?xml version="1.0" encoding="UTF-8"?>\r
 148 &lt;project name="MRGettingStarted" default="all" basedir=".">\r
 149     &lt;property environment="env" />\r
 150     &lt;!-- 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
 153     -->\r
 154     &lt;import file="${env.DBCK_HOME}/lib/build_fuse_common.xml"/>\r
 155 \r
 156     &lt;!-- Edit the following properties for your book: -->\r
 157     &lt;property name="ROOT" value="prog_guide" />    \r
 158     &lt;property name="DOCID" value="FuseMRProg" />\r
 159     &lt;property name="LOGO" value="fmr" />\r
 160     &lt;property name="CONDITIONS" value="fuse;comment" />\r
 161 \r
 162     &lt;!-- DO NOT MODIFY ANYTHING BELOW THIS LINE -->\r
 163     ...</programlisting>\r
 164       </example>\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
 167       <itemizedlist>\r
 168         <listitem>\r
 169           <para>Unmarked elements not enclosed by conditionalized elements are included in the\r
 170             output.</para>\r
 171         </listitem>\r
 172         <listitem>\r
 173           <para>Elements marked with the <code>artix</code> condition are\r
 174               <emphasis>excluded</emphasis> from the output.</para>\r
 175         </listitem>\r
 176         <listitem>\r
 177           <para>Elements marked with the <code>fuse</code> condition are\r
 178               <emphasis>included</emphasis> in the output.</para>\r
 179         </listitem>\r
 180         <listitem>\r
 181           <para>Elements marked with the <code>comment</code> condition are\r
 182               <emphasis>included</emphasis> in the output.</para>\r
 183         </listitem>\r
 184       </itemizedlist>\r
 185     </simplesect>\r
 186     <simplesect>\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
 193     </simplesect>\r
 194     <simplesect>\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
 201     </simplesect>\r
 202   </section>\r
 203 </chapter>\r