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.