RichFaces 3.3.X Docs Build Details

Version 10

    [This article is work in progress...]

     

    For simplified, step-by-step instructions for building and releasing the RichFaces 3.3.X documentation, refer to http://community.jboss.org/docs/DOC-13446

     

    For instructions for building the RichFaces 4.0.X documentation, refer to http://community.jboss.org/docs/DOC-13446

     

    Typical project structure

     

    There is a typical project structure of a guide:

    guide
    |-- en
    |   |-- pom.xml
    |   `-- src
    |       `-- main
    |           |-- docbook
    |           |   |-- master.xml
    |           |   |-- modules
    |           |   |   |-- module1.xml
    |           |   |   `-- module2.xml
    |           `-- resources
    |               `-- images
    |                   |-- image1.png
    |                   `-- image2.png
    `-- pom.xml
    

     

    The master.xml file contains the structure of a guide,  sometimes chapters and sections:

       

      <?xml version="1.0" encoding="UTF-8"?>
      <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
      "http://www.docbook.org/xml/4.3CR3/docbookx.dtd"[     
      <!ENTITY module1 SYSTEM "modules/module1.xml">
      <!ENTITY module2 SYSTEM "modules/module2.xml">
      ]>
      <book>
          <bookinfo>
              <title>Guide</title>
          </bookinfo>
          <toc/> 
          &module1;
          &module2;
      </book>
      

     

    Docs source format

    All RichFaces guides are written in DocBook format, 4.3 version.

     

    Docs styles

    All RichFaces guides use JBoss.org styles. CSS and XSL files of RichFaces project are inherited from JBoss.org styles you can find in org.jboss.jbossorg-docbook-xslt and org.jboss.jbossorg-jdocbook-style packages. "DocBook XSL: The Complete Guide" will help you to format all RichFaces guides successfully. All RichFaces *.xsl files are stored in the org.richfaces.docs.common-resources.xslt.

    Docs output formats

    There are 2 output formats now: (X)HTML and PDF. All RichFaces guides are built with the help of maven-jdocbook-plugin. There is a configuration sample for the plugin from pom.xml of the RichFaces Developer Guide:

    ...
    <configuration>
         <sourceDirectory>
              ${basedir}/src/main/docbook
         </sourceDirectory>
         <imageResource>
              <directory>
                   ${basedir}/src/main/resources
              </directory>
         </imageResource>
         <cssResource>
              <directory>
                   ${project.build.directory}/common-resources
              </directory>
         </cssResource>
         <sourceDocumentName>
              master.xml
         </sourceDocumentName>
         <formats>
              <format>
                   <formatName>pdf</formatName>
                   <stylesheetResource>
                        classpath:/common-resources/xslt/pdf-common.xsl
                   </stylesheetResource>
                   <finalName>
                        richfaces_reference.pdf
                   </finalName>
              </format>
              <format>
                   <formatName>html</formatName>
                   <stylesheetResource>
                        ${xsl_html}
                   </stylesheetResource>
                   <finalName>index.html</finalName>
              </format>
              <format>
                   <formatName>html_single</formatName>
                   <stylesheetResource>
                        ${xsl_html_single}
                   </stylesheetResource>
                   <imageCopyingRequired>
                        true
                   </imageCopyingRequired>
                   <imagePathSettingRequired>
                        false
                   </imagePathSettingRequired>
                   <finalName>
                        index.html
                   </finalName>
              </format>
         </formats>
         <xincludeSupported>true</xincludeSupported>
         <options>
              <xincludeSupported>true</xincludeSupported>
              <useRelativeImageUris>
                   true
              </useRelativeImageUris>
              <xmlTransformerType>
                   saxon
              </xmlTransformerType>
              <docbookVersion>1.72.0</docbookVersion>
         </options>
    </configuration>
    ...

     

    All information about formats and configuration options you can find at Usage of maven-jdocbook-plugin page.

     

    Docs dependencies

    There is a number of dependencies of guides:

    1. org.jboss.jbossorg-docbook-xslt, that contains *.xsl files with JBoss.org styles
    2. org.jboss.jbossorg-jdocbook-style, that contains *.css files and images that are common for all JBoss.org docs
    3. org.richfaces.docs.common-resources, that contains RichFaces XSL, CSS, JavaScript, and images
    4. org.apache.xmlgraphics.fop (Apache FOP) is a print formatter driven by XSL formatting objects (XSL-FO) and an output independent formatter
    5. com.uwyn.jhighlight - JHighlight is an embeddable pure Java syntax highlighting library that is used for XML and Java highlighting.

     

    Profiles

    Profiles are specified using a subset of the elements available in the pom.xml itself. Profiles modify the POM at build time, and are meant to be used as "variables" for the build. More details could be found at the Introduction to Build Profiles page. There is a list of available profiles of RichFaces Docs:

    1. release_docs, that is used to build documentation for release (without "Nightly Builds" banner). xhtml-single-release.xsl and xhtml-release.xsl are used for this build
    2. html, that is used to build (X)HTML mutlipage versions of guides
    3. html_single, that is used to build (X)HTML single versions of guides

    If you use RichFaces 3.3.X docs and would like to build all documentation from the root of the trunk you should use docs profile, because documentation building is excluded from the dev. build by default.

     

    RichFaces Guide Archetype

    There is the RichFaces Guide Archetype in the org.richfaces.docs.common-resources, that is used to new guides generation. In order to use this archetype,please, take the following steps:
    1. Build the archetype with "mvn clean install"
    2. Cd to RichFaces_trunk\docs\ and run the following command all in one line where artifactId is project folder name:
      mvn archetype:generate -DarchetypeGroupId=org.richfaces.docs
      -DarchetypeArtifactId=richfacesguide-archetype
      -DarchetypeVersion=3.3.1-SNAPSHOT -DartifactId=RichFacesGuide
      -DgroupId=org.richfaces.docs
    3. When the build is finished you will see the  (your project name folder). Cd to RichFacesGuide (your project name folder) and "mvn clean install" to build the guide.