[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

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.