My favorites | Sign in
Project Home Downloads Wiki Issues Source
READ-ONLY: This project has been archived. For more information see this post.
Search
for
BuildTelluriumReferenceDocumentWithDocbkxMavenPlugin  
Build Tellurium Reference Document with Docbkx Maven Plugin.
Phase-Design, Phase-Support
Updated May 5, 2010 by John.Jian.Fang@gmail.com

Introduction

Tellurium 0.7.0 starts to use docbook to build the reference document. What is docbook? We quote from http://docbook.sourceforge.net/, "DocBook is an XML vocabulary that lets you create documents in a presentation-neutral form that captures the logical structure of your content. Using free tools along with the DocBook XSL stylesheets, you can publish your content as HTML pages and PDF files, and in many other formats."

Maven

docbkx tools provides a number of tools supporting DocBook in a Maven environment including the Docbkx Maven Plugin. The good news is that the Docbkx Maven plugin supports DocBook version 5.0.

The Maven pom is as follows.

   <build>
        <plugins>
            <plugin>
                <groupId>com.agilejava.docbkx</groupId>
                <artifactId>docbkx-maven-plugin</artifactId>
                <version>2.0.10-SNAPSHOT</version>
                <executions>
                    <execution>
                        <id>documentation identifier</id>
                        <phase>pre-site</phase>
                        <goals>
                            <goal>generate-pdf</goal>
                        </goals>
                        <configuration>
                            <!-- per execution configuration -->
                            <includes>tellurium-reference.xml</includes>
                            <!--<draftMode>yes</draftMode>-->
                        </configuration>
                    </execution>
                </executions>
                <configuration>
                    <!-- shared configuration -->
                    <generatedSourceDirectory>${project.build.directory}/docbkx/generated</generatedSourceDirectory>
                    <xincludeSupported>true</xincludeSupported>
                    <paperType>A4</paperType>
                    <fop1Extensions>1</fop1Extensions>

                    <foCustomization>src/docbkx-stylesheet/fo/docbook.xsl</foCustomization>

                    <customizationParameters>
                        <!-- additional XSLT parameters-->
                        <parameter>
                            <name>key</name>
                            <value>value</value>
                        </parameter>
                    </customizationParameters>
                </configuration>
            </plugin>
        </plugins>
    </build>

    <pluginRepositories>
        <pluginRepository>
            <id>docbkx.snapshots</id>
            <name>Maven Plugin Snapshots</name>
            <url>http://docbkx-tools.sourceforge.net/snapshots/</url>
            <releases>
                <enabled>false</enabled>
            </releases>
            <snapshots>
                <enabled>true</enabled>
            </snapshots>
        </pluginRepository>
    </pluginRepositories>

The project structure is listed as follows.

[jfang@Mars tellurium-reference]$ tree .
.
|-- pom.xml
`-- src
    |-- docbkx
    |   |-- media
    |   |   |-- EngineGroupLocatingFlow.png
    |   |   |-- ExportToGroovySmall.png
    |   |   |-- FireFoxUserProfile.png
    |   |-- overview.xml
    |   |-- quickstart.xml
    |   |-- referenceprojects.xml
    |   |-- resources.xml
    |   |-- tellurium-reference.xml
    |   |-- trace.xml
    |   |-- trump.xml
    |   |-- udl.xml
    |   |-- uiobjects.xml
    |   |-- whatsnew.xml
    |   `-- widgets.xml
    `-- docbkx-stylesheet
        `-- fo
            `-- docbook.xsl

DocBook

Book

DocBook has two types, i.e., article and book. Tellurium reference uses the book format, which includes the following sections.

<?xml version="1.0" encoding="UTF-8"?>
<book version="5.0" xmlns="http://docbook.org/ns/docbook"
      xmlns:xlink="http://www.w3.org/1999/xlink"
      xmlns:xi="http://www.w3.org/2001/XInclude"
      xmlns:db="http://docbook.org/ns/docbook" xml:lang="en">
    <info>
        <title>Tellurium Automated Testing Framework</title>
        <subtitle>Reference Documentation</subtitle>
        <pubdate>May 15, 2010</pubdate>
        <releaseinfo>v0.7.0</releaseinfo>

        <authorgroup>
            <author>
                <firstname>Jian</firstname>
                <surname>Fang</surname>
            </author>
            ...
        </authorgroup>

        <copyright>
            <year>2010</year>
            <holder>TelluriumSource</holder>
        </copyright>

        <legalnotice>
            <para>Licensed under the Apache License, Version 2.0 (the "License"); you may not use this
                file except in compliance with the License. You may obtain a copy of the License at:
            </para>
            <para>
                http://www.apache.org/licenses/LICENSE-2.0
            </para>
            <para>
                Unless required by applicable law or agreed to in writing, software distributed under the
                License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
                CONDITIONS OF ANY KIND, either express or implied. See the License for the specific
                language governing permissions and limitations under the License.
            </para>
        </legalnotice>

     </info>

Chapter

Each chapter has the following XML format. For example, the overview.xml is as follows.

<?xml version="1.0" encoding="UTF-8"?>
<chapter version="5.0" xmlns="http://docbook.org/ns/docbook"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xmlns:xi="http://www.w3.org/2001/XInclude"
         xmlns:ns5="http://www.w3.org/2000/svg"
         xmlns:ns4="http://www.w3.org/1998/Math/MathML"
         xmlns:ns3="http://www.w3.org/1999/xhtml"
         xmlns:db="http://docbook.org/ns/docbook">

    <title>Overview of Tellurium</title>
    
    <section>
        <title>What is Tellurium</title>
    ...

<chapter>

Then in the main XML file tellurium-reference.xml, we can include the xml file in the following way.

    <xi:include href="overview.xml"/>

    <xi:include href="whatsnew.xml"/>

    <xi:include href="quickstart.xml"/>

Similarly, the appendix is defined as:

<appendix version="5.0" xmlns="http://docbook.org/ns/docbook"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xmlns:xi="http://www.w3.org/2001/XInclude"
         xmlns:ns5="http://www.w3.org/2000/svg"
         xmlns:ns4="http://www.w3.org/1998/Math/MathML"
         xmlns:ns3="http://www.w3.org/1999/xhtml"
         xmlns:db="http://docbook.org/ns/docbook">

     <title>FAQs</title>
     ...

</appendix>

section

section can be nested in docbook, for example.

    <section>
        <title>Setup Tellurium Project in IDEs</title>
        <para>A Tellurium Project can be run in IntelliJ, NetBeans, Eclipse, or other IDEs that have
            Groovy support.
        </para>

        <para>If using Maven, open the POM file to let the IDE automatically build the project files.
        </para>

        <section>
            <title>IntelliJ IDEA</title>
            <para>
                IntelliJ IDEA Community edition is free and can be downloaded from 
            </para>

        </section>
       ...
  <section>

Link

External links can be defined with xlink:href.

<para>
  IntelliJ IDEA Community edition is free and can be downloaded from<link xlink:href="http://www.jetbrains.com/idea/download/"> http://www.jetbrains.com/idea/download/</link>. A detailed guide is found on<link xlink:href="http://code.google.com/p/aost/wiki/CustomTelluriumIntelliJProject">How to
 create your own Tellurium testing project with IntelliJ 9.0 Community Edition</link>.
</para>

For internal links, i.e., section references, we can use linkend. For example, we first define an id for a section,

<section id="samplepom">
    <title>settings.xml</title>
    ...
</section>

then reference that section with link.

<para>
   A sample POM file can be found in
   <link linkend='samplepom'>this appendix</link>.
</para>

Image

<mediaobject>
   <imageobject>
      <imagedata fileref="./media/tellurium3.png" scalefit="1" width="100%"></imagedata>
   </imageobject>
</mediaobject>

where scalefit is an option to fit to the width. Another option is scale to change the image size.

screen

screen is used to show console output.

<screen>
   java -jar selenium-server.jar -singlewindow
</screen>

programlist

programlist is used to include code snippet.

<programlisting language="java"><?db-font-size 75% ?>
<![CDATA[
ui.Form(uid: "Form", clocator: [tag: "form"]){
   Div(uid: "User", clocator: [:]){
      Selector(uid: "Sex", clocator: [:])
      InputBox(uid: "Input", clocator: [tag: "input", type: "text",
                name: "j_username"])
   }
   Container(uid: "Finish", clocator: [tag: "tr"]){
      SubmitButton(uid: "Submit", clocator: [tag: "input", type: "submit",
                value: "Login", name: "submit"])
   }
}
]]>
</programlisting>

where <?db-font-size 75% ?> is used to scale the code font size. In the meanwhile, the xsl style sheet must use the following transformation to change font size.

    <xsl:attribute-set name="monospace.verbatim.properties">
      <xsl:attribute name="font-size">
        <xsl:choose>
          <xsl:when test="processing-instruction('db-font-size')"><xsl:value-of
               select="processing-instruction('db-font-size')"/></xsl:when>
          <xsl:otherwise>inherit</xsl:otherwise>
        </xsl:choose>
      </xsl:attribute>
    </xsl:attribute-set>

list

itemlist is used to represent a list, for example.

<itemizedlist>
   <listitem>
      <para>tellurium-junit-archetype</para>
   </listitem>
   <listitem>
      <para>tellurium-testng-archetype</para>
   </listitem>
</itemizedlist>

If we need an ordered list with number index, we can use orderedlist instead.

<orderedlist>
   <listitem>
      <para>address the dynamic factors in Tellurium UI templates</para>
   </listitem>
   <listitem>
       <para>increase the flexibility of Tellurium UI templates.</para>
   </listitem>
</orderedlist>

table

the table tag is used to represent a table in docbook. For example.

         <table id="uiobjectattributes">
          <title>UI Object Attributes</title>
          <tgroup cols="2">
            <colspec colname="c1" colwidth="1*" />
            <colspec colname="c2" colwidth="1*" />
            <thead>
              <row>
                <entry>ATTRIBUTE</entry>
                <entry>DESCRIPTION</entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry>UI Object</entry>
                <entry>Basic Tellurium component</entry>
              </row>
              <row>
                <entry>UiID</entry>
                <entry>UI object's identifier</entry>
              </row>
              <row>
                <entry>Namespace</entry>
                <entry>Used for XHTML</entry>
              </row>
           </tbody>
          </tgroup>
        </table>

Tools

There are couple tools to convert docBook to and from different formats. For example, we can use the following command herold to convert html to docbook.

herold --in=udl.html --out=udl.xml -r book -T

But the converted docbook version is 1.0 and we still need manually change some docbook formats in the converted file.

Resources

Powered by Google Project Hosting