Sunday, December 12, 2010

How to Use docbkx-tools as Maven DocBook plugin

When it comes to documentation of open source projects, DocBook is the favorite choice among many developers. As you all know, DocBook provides a comprehensive XML schema to document your project, which you can transform to any format such as html, pdf, webhelp etc. Here, I'm going to show you how to integrate DocBook in to your Maven project via docbkx-tools. This docbkx-maven-plugin makes docbook integration to Apache Maven much easier.

Reference DocBook XSLs from your customization layer
Probably you are not planning to use DocBook standard stylesheets alone, but have a little more customization to it. For that, you have to create a new customization layer, and import the standard docbook.xsl stylesheet. 
It's a little tricky how it's done in this plugin. You should give a symbolic reference rather than an actual file location when importing the stylesheets. You should use <xsl:import href="urn:docbkx:stylesheet/docbook.xsl" /> to give the symbolic reference.
What "urn:docbkx:stylesheet" refers will depend on what customization (html, xhtml, etc.) you want to use. If you want to use xhtml/chunk.xsl customization, first specify it in your XSL by     <xsl:import href="urn:docbkx:stylesheet/chunk.xsl"/> and then, in your POM, specify the <xhtmlCustomization>. Further details are explained below.

Integrating dockbkx-tools to Maven projects
OK, now let's see how to integrate this nice Docbook plugin to your maven project.
  • First, you have to add the docbook plugin to your parent POM file pom.xml. The docbook xml documentation should be on path trunk/src/docbkx.
    <build>
        <plugins>
            <plugin>
                <groupId>com.agilejava.docbkx</groupId>
                <artifactId>docbkx-maven-plugin</artifactId>
                <version>2.0.11</version>
                <dependencies>
                    <dependency>
                        <groupId>org.docbook</groupId>
                        <artifactId>docbook-xml</artifactId>
                        <version>4.4</version>
                        <scope>runtime</scope>
                    </dependency>
                </dependencies>
                <configuration>
                    .......
                </configuration>
                <executions>
                    ......
                </executions>
            </plugin>
        </plugins>
    </build>

As you can see, the plugin depends on the docbook-xml artifact. After adding this structure to your POM, you just have to customize it according to your needs.
  • Then, you have to set the configurations in <configuration> tag. In that, you should menion the xsl customization file, if you have a customized docbook XSLs. Else, you can just use the generic XSLs provided by DocBook. At this point, the docbkx's version is 2.0.11 and it uses DocBook-XSL-NS 1.75.2  version. Mind that it's the namespace version, so make sure you make your customized version with NS too. Else, you may encounter errors which could be hard to track. For the customizations, for html, use <htmlCustomization> tag to mention the customizations. For PDF, it's <foCustomization>. and <xhtmlCustomization> for, obviously, xhtml. A sample is below. You may put configurations under <executions> too, if you wish.
  • The new customization to the DocBook-XSL family, DocBook WebHelp, is not yet included on this version, but the people are working on it to make it available as soon as possible. I'm eagerly waiting for it, mainly because I contributed to it a lot; plus it's a nice customization which you can actually put in the web for your audience to see.
        <configuration>
            <foCustomization>src/docbkx/xsl/fo.xsl</foCustomization>
            <xhtmlCustomization>src/docbkx/xsl/xhtml.xsl</xhtmlCustomization>
        </configuration>                
  • Now it's to set the 'executions' you need to run. Executions specify what goals you run, copy CSS/JavaScript files you might have etc. A sample execution code is given below.

        <executions>
            <execution>
                <id>userguide</id>
                <phase>pre-site</phase>
                <goals>
                    <goal>generate-xhtml</goal>
                </goals>
                <configuration>
                    <includes>userguide.xml</includes>
                    <targetDirectory>target/site/userguide</targetDirectory>
                    <chunkedOutput>true</chunkedOutput>
                    <xhtmlCustomization>src/docbkx/xsl/userguide.xsl</xhtmlCustomization>
                    <postProcess>
                        <copy todir="target/site/userguide/">
                            <fileset dir="src/docbkx/template">
                            </fileset>
                        </copy>
                    </postProcess>
                </configuration>
            </execution>
        </executions>  

What happens there? First, it specifies the phase 'pre-site', which tells to Maven that, this execution should be run first when invoking 'mvn site' command. 
    • <goal> - is set to generate-xhtml which will generate a xhtml output. Other options are generate-html and generate-pdf.
    • <includes> - This tag specifies which document should be processed. The path was trunk/src/docbkx/userguide.xml.
    • <configuration> - Then it comes to the configuration part. Most of it are self understandable. As you can see I've set the XSL customization I wish to use there. You can put it anywhere, both worked fine for me. 
      • <chunkedOutput> will generate set of html files rather than one BIG html file which are broken down based on the tags <chapter>, <section> etc. in your docbook xml file.
      • I copied all the CSS/JavaScript/Images to target folder by using the <postProcess> tag. It's easier. The source files were at src/docbkx/template.
  • You may write another <execution> to generate the PDF output. The whole code I used is given below.

        <build>
            <plugins>
                <plugin>
                    <groupId>com.agilejava.docbkx</groupId>
                    <artifactId>docbkx-maven-plugin</artifactId>
                    <version>2.0.11</version>
                    <dependencies>
                        <dependency>
                            <groupId>org.docbook</groupId>
                            <artifactId>docbook-xml</artifactId>
                            <version>4.4</version>
                            <scope>runtime</scope>
                        </dependency>
                    </dependencies>
                    <configuration>
                        <foCustomization>src/docbkx/xsl/fo.xsl</foCustomization>
                    </configuration>
                    <executions>
                        <execution>
                            <id>userguide</id>
                            <phase>pre-site</phase>
                            <goals>
                                <goal>generate-xhtml</goal>
                            </goals>
                            <configuration>
                                <includes>userguide.xml</includes>
                                <targetDirectory>target/site/userguide</targetDirectory>
                                <chunkedOutput>true</chunkedOutput>
                                <xhtmlCustomization>src/docbkx/xsl/userguide.xsl</xhtmlCustomization>
                                <postProcess>
                                    <copy todir="target/site/userguide/">
                                        <fileset dir="src/docbkx/template">
                                        </fileset>
                                    </copy>
                                </postProcess>
                            </configuration>
                        </execution>


                        <execution>
                            <id>userguide-pdf</id>
                            <goals>
                                <goal>generate-pdf</goal>
                            </goals>
                            <phase>compile</phase>
                            <configuration>
                                <includes>userguide.xml</includes>
                            </configuration>
                        </execution>
                    </executions>
                </plugin>
            </plugins>
        </build>
YBQQQSEANSZ5

8 comments:

  1. Hi Kasun,
    Thanks for your awesome work with the Docbook WebHelp project.
    We are currently experimenting with publishing technical documentation using Maven - Docbkx plugin.
    Is there any way, we can tweak this plugin to support a TOC based output just like the docbook webhelp project?

    Thanks,
    Ruchita

    ReplyDelete
  2. Hi Kasun.

    Can you please provide some example of using a custom stemmer for maven plugin. I want to use a Russian stemmer, but i can't to find a way for it.

    Best regards. Alexey

    ReplyDelete
  3. Hi Kasun,
    I try to use profiling with docbkx and Webhelp. Do you have any hints how to achieve this
    Best regards,
    Michael

    ReplyDelete
  4. Hi Kasun,
    I try to use profiling with Docbkx and Webhelp. Do you have any hints how to achieve this?
    Best regards,
    Michael

    ReplyDelete
  5. I have been banging my head against the wall trying to understand how the plugin can be told to look for other things you might want to import. Two examples:

    my customization layers import not just the regular stylesheet, but also the custom titlepages xsl I generated by the usual process

    I have a template to write a chunk of additional code into the HTML output's head element. Specifically, it's the code to hook up to Google Analytics.

    In both cases the files being imported are sitting in the same directory as the customization layer, but best as I can tell the plugin can't find them.

    Any ideas?

    ReplyDelete
    Replies
    1. You just need to set the main XSL that you use to process your document. It should go under element in the docbkx-maven-plugin plugin configuration.
      Just place the xsl files you want to import alongside the main xsl file. Then, refer to it via a relative path with .

      Delete
  6. This comment has been removed by the author.

    ReplyDelete
  7. I'm not following something. When you say "It should go under element in the docbkx-maven-plugin plugin configuration," you are talking about the pom.xml file, right? I have this in there in the configuration:

    <htmlCustomization>src/main/docbkx/custom-article-html.xsl</htmlCustomization>

    That's what tells the docbkx plugin where to find my xsl file, right?

    In that file, I have this import statement for the titlepages:

    <xsl:import href="./instart-technote-html-titlepage.xsl"/>

    The titlepage xsl file is in the same directory as the customization file - that is, in src/main/docbkx/.

    I also have this template to insert the Google Analytics script into the head of the output documents:

    <xsl:template name="user.header.content">
    <xsl:variable name="codefile" select="document('./ga.xml',/)"/>
    <xsl:copy-of select="$codefile/htmlcode/node()"/>
    </xsl:template>

    where the file ga.xml is also present in the same directory.

    When I run the project, the output has no titlepage information in it and no Google Analytics code in the head. In the Maven console I see this about the ga.xml file:

    Recoverable error
    Failure reading jar:file:/Users/alanoehler/.m2/repository/net/sf/docbook/docbook-xsl/1.76.1/docbook-xsl-1.76.1-ns-resources.zip!/docbook/html/ga.xml: JAR entry docbook/html/ga.xml not found in /Users/alanoehler/.m2/repository/net/sf/docbook/docbook-xsl/1.76.1/docbook-xsl-1.76.1-ns-resources.zip

    but nothing about instart-technote-html-titlepage.xsl.

    I've tried putting src/main/docbkx/ as in the pom file in place of ./ and that doesn't work. Then I do get a message about instart-technote-html-titlepage.xsl and the build just stops at the first file:

    Error at xsl:import on line 12 of file:/Users/alanoehler/Documents/repo/freshkido/external-docs/src/main/docbkx/custom-article-html.xsl:
    Failure reading file:/Users/alanoehler/Documents/repo/freshkido/external-docs/src/main/docbkx/src/main/docbkx/instart-technote-html-titlepage.xsl: /Users/alanoehler/Documents/repo/freshkido/external-docs/src/main/docbkx/src/main/docbkx/instart-technote-html-titlepage.xsl (No such file or directory)

    ReplyDelete