Posted by fabriziogiudici
on March 6, 2011 at 10:59 PM PST
Ok, I'm writing a book. But I don't know if I'm really able to write a book: if I look around at people who I know and who wrote a book in the past, I'm really unsure about my skills. But it's not meant as a "regular" book, I mean, something that gets published by an editor. It's just the collection of my design knowledge, in form of a comment to the code that I've written in my many projects, and it's meant to be a teaching support for my classes and mentoring sessions for customers. The problem is that as time goes on I fear more and more to forget stuff. Well, in the standard life forgetting things has got a meaning (it's a natural clean up and sometimes re-discovering forgotten stuff is a sweet thing), but in the professional world forgetting part of your experience is a loss of value.
So, back to my book. Regular or not, in any case it's written as a software engineering book, with text and code chunks. I've been convinced time ago to use DocBook . You type in XML (well, no worse than using LaTeX ) and convert it into HTML and PDF. Frustrating as it might appear in the iPad age, in the end it's much better than using a WYSIWIG such as OpenOffice or Microsoft Word (I've tried with the former, and gave up. I'm moving to writing my first photography book - another thing I'm doing - with DocBook too).
But inserting code chunks has been a pain so far. The problem is not actually formatting some text as a Java listing, but to keep the book in sync with the code - because you bet that the code is continuously evolving and even more when you focus on it because you have to explain it to somebody else. Keeping on with cut & paste was so inefficient that in one year I was able to write twenty pages. Figure it out.
I knew that people who wrote a book with DocBook used some sort of automated tool to import the code from real samples. But, as far as I know, no tool has been publicly released. BTW, you don't only need to import the code sample as is: you for sure need to remove block comments, eventually strip the package and the imports (but not always), sometimes you want also to suppress some section that is not relevant to your current focus, other times you want only to insert selected parts. So, you need some post-processing of the code.
In the end, I wrote my own tool. It's called BlueBook and instead of what you might find obvious, that is getting the sources from a local path or an SCM URL, it refers to a Maven artifact (of course, a Maven source artifact). It's a Mojo itself, so the book is a Maven project, that can also be run under Hudson. While it's very young (v1.0), and it especially suffers from the awful verbosity of its configuration (it's embedded in the POM configuration, I need to rewrite it as an external configuration), it's already effective. in a few weeks I've been able to write fifty pages more and I'm having fun with it.
Furthermore, the idea of using Maven artifacts seems to scale up with new features. For instance, I'm working on getting the UML diagrams that have been automatically created by UmlGraphDoc and published into a javadoc Maven artifact. Stay tuned.
Of course it's free and open and it's my first project hosted at the new java.net .
PS If you can read this, it's my first blog at the new Java.Net.