2 Replies Latest reply on Mar 8, 2010 8:41 PM by dmison

    conditional includes

    jhalliday

      Does the processing done by jDocBook/publican allow for conditional includes?

       

      My use case is a project which can be built in various configurations for various target environments. The raw documentation is a superset of that included in any given build. I want to annotate the docs such that some elements (anything from a sentence to an entire chapter) are identified as being relevant only to certain build types. Then at build time only the relevant content will be assembled and the rest left out. XSTL will handle that easily, but would require a separate pre-processing step to transform the raw XML into the build specific version before the jDocBook/publican step. It would be preferable to have the transform done in a single step.

        • 1. Re: conditional includes
          jaredmorgs

          Hi Jonathan

           

          I don't know of a way to do what you want to do without having Maven pre-process your XML.  Mobicents [1] have been experimenting with Maven pre-processing.  You may want to reach out to them about their successes with this approach.

           

          We don't recommend using conditional formatting in your documentation, because it tends to cause problems with translation and can complicate your build process.

           

          For a more succinct explanation, I would strongly recommend that you read the section on conditional formatting in the Publican User Guide [2].

           

          [1] www.mobicents.org

          [2] http://jfearn.fedorapeople.org/Publican/chap-Users_Guide-Creating_a_document.html#sect-Users_Guide-Conditional_tagging

          • 2. Re: conditional includes
            dmison

            The conditional inclusion of elements in docbook is called profiling, http://www.sagehill.net/docbookxsl/Profiling.html

             

            The major differences:

            Publican:

            • only supports the condition profile attribute as referred to in the publican user guide.
            • honors the condition attribute in <xi:include> (arguably not valid)
            • will report an empty .xml file as invalid so if a file only has  <chapter condition="blah"> and condition is not set to blah it will not build.  You need to put the condition attribute in the <xi:include>

             

            jDocbook:

            • supports all the profiling attributes, but only one per build.
            • does not honor profiling attributes in <xi:include>
            • doesn't choke on empty .xml files (arguable a bug)

             

            For compatibility between the two you might want something like:

             

            <book>
                 <xi:include href="chapt-about.xml" /> <!-- a chapter -->
                 <chapter condition="developer">
                      <title>Developer Introduction </title>
                      <xi:include href="chapt-content-developer_intro.xml" />
             
                 </chapter>
                 <chapter condition ="administrator">
                      <title>Administrator Introduction</title>
                      <xi:include href="chapt-content-admin_intro.xml" />
             
                 </chapter>
            </book>
            

             

             

            Setting up profiling in jDocbook ( I'm not aware of this being documented anywhere yet apart from MPJDOCBOOK-40 )

             

            You need to set the profiling attribute and value for it in the POM

             

            <configuration> 
                 <profiling> 
                      <enabled>true</enabled> 
                      <attributeName>condition</attributeName> 
                      <attributeValue>developer</attributeValue> 
                 </profiling> 
            </configuration> 
            

             

            To pass in different values for different builds you would probably want to put this configuration in different profiles in the POM

             

            <profiles>
                
                <profile>
                    <id>dev_guide</id>
                    <build>
                        <plugins>
                            <plugin>
                                <groupId>org.jboss.maven.plugins</groupId>
                                <artifactId>maven-jdocbook-plugin</artifactId>
                                <version>2.2.0</version>
                                <extensions>true</extensions>
                                <configuration> 
                                    <profiling> 
                                        <enabled>true</enabled> 
                                        <attributeName>condition</attributeName> 
                                        <attributeValue>developer</attributeValue> 
                                    </profiling> 
                                </configuration> 
                            </plugin>
                        </plugins>
                    </build>
                </profile>
            
                <profile>
                    <id>admin_guide</id>
                    <build>
                        <plugins>
                            <plugin>
                                <groupId>org.jboss.maven.plugins</groupId>
                                <artifactId>maven-jdocbook-plugin</artifactId>
                                <version>2.2.0</version>
                                <extensions>true</extensions>
                                <configuration> 
                                    <profiling> 
                                        <enabled>true</enabled> 
                                        <attributeName>condition</attributeName> 
                                        <attributeValue>administrator</attributeValue> 
                                    </profiling> 
                                </configuration> 
                            </plugin>
                        </plugins>
                    </build>
                </profile>
                
            </profiles>