Common Java Cookbook: Release 0.7: Fixed ID References


Alright, this is a very simple, technical release that fixes ID references in the book. I was working with the pre-print DocBook XML from O’Reilly which contained some unreadable IDs for sections. A section about reversing a String with StringUtils had the ID “jakarta-ckbk-CH-1-SECT-6”, and a chapter on Commons Collections would have the ID “jakarta-ckbk-CH-4”. I’m a big believer in making the IDs of sections human readable, and I’m also against encoding section numbers into the ID for a section. In this release I assigned more reasonable identifiers to chapters and sections.

Read the Common Java Cookbook Online

This also has the side-effect of making the URLs for the book more comprehensible for users (not to mention analytics). IMO, URLs should give some idea of content: “/books/cjcook/reference/jakarta-ckbk-CH-5-SECT-15.html” seems useless to me, where “/books/cjcook/reference/functors-sect-iterating.html” seems more reasonable. One of the lessons I learned from the Maven book was that you should try to solidify your URLs early on in the process and introduce a few changes as possible. A common naming strategy for sections and chapters is going to make it easy to craft rewrite rules as structural changes are introduced to the text (and, trust me, structual changes are going to happen to this book). Really, I’m trying to avoid ever having to figure out what an ID like “jakarta-ckbk-CH-5-SECT-15” means and then, worse, trying to craft a meaningful rewrite rule when Chapters are rearranged.

Common Java Cookbook: 0.7: Consistent Internal ID References from Tim O'Brien on Vimeo.