FWIW, the
Eclipse Project Handbook is in Asciidoc. We initially used AsciiDoc to convert, but switched to
Asciidoctor which, frankly, does a better job, has great documentation, and has lots of options including some sweet Maven plugins.
The repository is here:
I've done most of the work. There's a lot of discovery in the content that I've been stabilizing over the years, so I can't say with confidence that every aspect of the repo constitutes a "best practice".
I am, however, pretty happy with the way that I've used includes to assemble the document and my use of substitution variables to support different flavours of the document (we used to produce specific versions that combine the content in different ways for the PolarSys and LocationTech working groups).
e.g. the
eclipse.adoc root document shows how the "Eclipse" version is assembled.
If you look at the chapters, you'll notice that I use Graphviz for most of the diagrams (which are rendered as SVG). It does import a handful of bitmap images as well (mostly screenshots).
I have it set up to render the HTML as a complete document with the images embedded. This was a choice that made it easier to move the content around (we used to deploy the PolarSys and LocationTech versions as Drupal documents, and it's way easier to do so with embedded images).
The PDF generation is basically out-of-the-box stuff that I haven't attempted to tune. The EPUB generation is broken; fixing it is a bit of a nice-to-have right now, so it hasn't been a priority.
Note that the repository does have a submodule to include the EDP as an appendix, so if you clone this repository be sure to use the --recursive switch.
The README includes some comments about tools that I used to import the content from the variety of original sources. Basically pandoc is your friend. There's a couple of switches in there to get it pull in content in the right format. I've used it to pull in straight HTML, mediawiki wikitext from Eclipsepedia, and a smattering of Word documents. In all cases, I spend a great deal of effort tuning, but mostly to try and massage content from a multitude of sources into as coherent a form as possible (still very much a work-in-progress).
Small note, I decided to avoid hard wrapping in the adoc source to make it easier to do diffs and avoid pure reformatting commits.
Random thought... if all specs are in Asciidoc format, creating a book that includes all of these specs together in one place would be pretty trivial. One possible consideration is to encourage a best practice for naming link anchors that avoids collisions.
Again, there are some of what I might consider best practices in the repo, but also a lot of stuff that are the results of me fumbling around trying to make it go (I'd avoid looking for too many best practices in the
pom.xml).
Wayne
--
Wayne Beaton
Director of Open Source Projects | Eclipse Foundation, Inc.
