I’ve been asked about the technology used in the new Eclipse Project Handbook.
The content itself is specified in Asciidoc format and rendered into HTML using Asciidoctor. I started off using Asciidoc for rendering, but changed after I ran into a couple of bugs and problematic licensing.
The content is represented as a collection of documents that are combined via master documents for each of the separate forges; I decided to do this to make the content more manageable and easier for contribution, and make it more easy to mix and match content. Forge-specific parameters are specified in the master document.
Many of the images are specified using Graphviz and rendered as hierarchical images using dot. For this style of graphic, the very simple text format permitted by Graphviz means that I have very good version control for these images. I also really hate pushing pixels around.
To render the documents as PDF, I’m using Asciidoctor to render the content in Docbook format and Apache FOP to take it the rest of the way. I think that my challenges with the graphics in the rendered PDFs are a issue with FOP, but haven’t quite concluded my investigation. As I mentioned yesterday, I consider the PDF versions a nice-to-have, so I haven’t made sorting this out a very high priority.
I’m pulling all the pieces together using a make build. Given the nature of the project, this was, frankly, the easiest solution. It works well and is easy to maintain (there are, however, a few hard-coded file paths that I’m not at happy about).
The sources are all in the /projects Git repository if you’d like to take a closer look. I’m thinking that I will move these to a separate repository to make it easier for folks who want to contribute patches (so that you don’t need to clone all the other junk stuff in that repository).
Naturally, I’m using Eclipse to edit content and invoke the makefile as an external tool. Adding Mylyn Docs Wikitext support for Asciidoc to my Eclipse configuration is on my to-do list this month.
I’m pulling all of the tools from the Fedora software repository.
