Maven Definitive Guide Project Infrastructure


April 29, 2009 By Tim O'Brien

open-sourceNote: Before we get started, anyone interested in signing up for Maven training should do so soon. We’ve got a class in Mountain View, CA on May 12-13, and a class in Chicago on May 19-20. Sign up today. It’ll be great, and we’ve got some new material from John Smart, author of “Java Power Tools”.

Alright, we’ve put the infrastructure in place for more participation in the development of Maven: The Definitive Guide. We’ve already had two forks of the Definitive Guide on GitHub. People are interested in helping out, and we encourage anyone to either submit a patch or fork and start innovating. Read on for some more details, how to sign up for our author mailing list, register for an account in the issue tracker, and get started with the code:

Mailing List + JIRA + Github

Building the Book

Prerequisites Maven 2.0.9 or higher (will soon switch to 2.1.0 or possibly 3.0). You will also need to install the Java Advanced Imaging (JAI) binaries which can be found here. Since the book build uses FOP + Batik, you need the JAI library as it is required to place the images in the PDF version of the book. If you are not interested in building the PDF version of the book, you can build the project without JAI, but you’ll end up with an imageless PDF.

To build the book, clone the Github repo and run “mvn install”. This process is going to take forever, but, once done, you’ll have copies of the book HTML and PDF in content-en/target/. If you don’t want to wait for all the various languages to generate HTML and PDF, just go into a directory like “content-en” and run “mvn install”.

Writing the Book

We use XMLMind which is a DocBook editor written in Java. XMLMind isn’t free, but there is a Personal Edition which you can use if you are not using the editor for Commercial reasons. Clearly, I’ve got a Professional license because I’m using this tool in a commercial setting every single day. Do you need a Pro license if you are contributing to an open source project? XMLMind has carved out an exception to the Personal Edition license that allow people to use the Personal Edition to modify documents covered under an accepted OSI license. As the Creative Commons is an accepted OSI license, I would assume that some of you might accept that XMLMind Personal can be used to participate in this open source project.

I will say a few things about XMLMind, it’s a cantankerous tool for most people during the first year of use. You’ll warm to it very, very slowly if you have the patience to learn it. The key to using this tool profitably is to learn the numerous keyboard shortcuts and to understand that it is not a simple WYSIWYG word processor. If you are interested in learning about the tool that many of us use to write large, complex documents read Jim Elliott and Marc Loy’s Getting Productive with XMLMind.

Editing DocBook by hand is going to drive you insane. I wouldn’t recommend it. Also there are some features of DocBook you might want to avoid. Callouts in particular are a labor-intensive device that should be used sparingly. If anyone wants me to put together a long explanation of why we use DocBook, I’ll be happy to do so. It all boils down to: “I’ve written books in Word Processors before, and it was painful”…

Tomorrow, I’ll write a quick overview of the project structure and I’ll describe the structure of the build.