Build environment

I've created the git repo as doc/manual and set up permissions such that Richard can push to it.

I've also set up two Jenkins jobs:
https://newbuild.whamcloud.com/job/lustre-manual/
https://newbuild.whamcloud.com/job/lustre-manual-reviews/

These are configured similarly to the regular lustre jobs – lustre-manual periodically (once an hour) polls the master branch of the doc/manual repo and builds any changes it sees, whereas lustre-manual-reviews is triggered by individual Gerrit reviews.

Currently, there seems to be a problem in generating PDFs with fop. As I'm unfamiliar with these tools, I'll hand this task back to Richard for resolution. If there are packages which need to be installed, please update this issue and I'll take care of them.

Mike and I have made some progress on this issue: there is a RHEL6 package 'docbook5-style-xsl' that reduces the warnings to zero during the xsltproc transform. Fop still fails.

It seems that there is a problem with the version of fop that is included with RHEL6 with the docbook we've generated. The version 1.0 from here:

http://apache.deathculture.net/xmlgraphics/fop/binaries/

generates a PDF.

Mike: is possible to add a 1.0 fop requirement?

Can we add a dependence on fop 1.0?

Did you build/run fop-1.0 on RHEL6? I managed to package it, but it fails with the following:

Exception in thread "main" java.lang.NoClassDefFoundError: org/apache/xmlgraphics/util/uri/CommonURIResolver

This is apparently due to a missing xmlgraphics-commons-1.4.jar. I located one and downloaded it, and as an experiment made it available to fop via CLASSPATH. I managed to get a bit further, but ran into this:

SEVERE: Couldn't find hyphenation pattern en

This is apparently due to a missing fop-hyph.jar, which I also downloaded and made available via CLASSPATH. Now it fails with the following:

Exception in thread "main" java.lang.NoSuchMethodError: org.apache.xmlgraphics.java2d.GraphicContext.<init>(Lorg/apache/xmlgraphics/java2d/GraphicContext;

I think, given that I have been poking at this for most of a day when I'm supposed to be working on Hydra, that I'm going to have to push back on this request. Please find a way to generate the manual which works with the packages provided by RHEL6, or else package up the necessary tool stack and push it to the toolkit repo.

Mike, Thanks for your time on this.

As you instruct, I've been looking at creating a fop workflow on a vanilla RHEL6 machine. I have had a look at the fop package you've built and I believe that the dependency on xmlgraphics-commons needs to be:

Requires: xmlgraphics-commons >= 1.4

I've created a change for this: http://review.whamcloud.com/#change,998

There are RPMs of xmlgraphics-commons >= 1.4 available (i.e. on pbone.net), but they not as part of the RHEL6 distro. In addition the RPM I looked at has a dependency on 'apache'-commons-io and 'apache'-commons-logging. I believe the equivalent packages in RHEL6 are 'jakarta'-commons-io and 'jakarta'-commons-logging. By forcing the rpm install of xmlgraphics-commons.1.4.rpm, and then installing your fop.1.0.rpm. I can generate a pdf manual.

I've taken the xmlgraphics-commons source, created a .spec that corrects the dependency from apache to jakarta. This change is: ://review.whamcloud.com/#change,999

Steps to build pdf manual.

1. Install java yum install java
2. create a fop version of the manual

   # xsltproc --stringparam  fop1.extensions  1 --stringparam  section.label.includes.component.label 1 --stringparam  section.autolabel 1 --stringparam  chapter.autolabel 1 --stringparam  appendix.autolabel 1 --xinclude -o /tmp/manual.fo /usr/share/sgml/docbook/xsl-ns-stylesheets-1.75.2/fo/docbook.xsl ./index.xml
   Making portrait pages on USletter paper (8.5inx11in)
   

3. Observe no errors are returned.
4. install jakarta-commons-io and jakarta-commons-logging
5. install xmlgraphics-commons from build.whamcloud.com/toolkit
6. Install fop from build.whamcloud.com/toolkit
7. Convert the fop file to a pdf using fop:

   # fop /tmp/manual.fo /tmp/manual.pdf
   

NOTE the fop job creates a bunch of warnings. I think these are acceptable at this stage but should be tidied up in future.

NOTE: xmlgraphic-commons introduces additional dependencies during build:

ant-junit junit jakarta-commons-io jakarta-commons-logging

Manual now builds, Hudson hooked into Gerrit: Thanks Mike!