Skip to main content
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
Re: [jakarta.ee-spec.committee] Asciidoc example
I'm not an expert in this area.  :-)  I've been using "asciidoc" to refer to the data format.  We never use the standalone program.  We've been using asciidoctorj with jbake to generate the html versions of the documents.

We do have an open issue to generate a PDF for the tutorial.  The suggestion is to do as you say and generate an index.adoc file with a bunch of includes.  It's a bit more complicated than that because the adoc files all include the jbake header.  The good news is that the header tells how all the files link together to form the complete document.

I did write a Maven plugin to generate the Table of Contents for the asciidoc files we have.  It works with the particular asciidoc style for our converted FrameMaker documents, but it's probably not general purpose.  Still, I haven't published the plugin, and we're not using it; the TOC needs to be maintained manually.

Since the plugin knows how to walk all the adoc files and read the jbake header, I could probably expand the plugin to generate an index.adoc file with includes.  Maybe I'll try to find some time to do that...


Is there anyone out there who is good with Graphviz and SVG?  There's a few diagrams in the platform spec that were created in a tool that is long dead.  I'd love to have someone recreate them with something maintainable.  You can see the diagrams in the Java EE 8 platform spec.  Any volunteers?

Who's planning to create the Jakarta EE 8 platform spec?


Wayne Beaton wrote on 1/30/19 11:00 AM:
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.


_______________________________________________
jakarta.ee-spec.committee mailing list
jakarta.ee-spec.committee@xxxxxxxxxxx
To change your delivery options, retrieve your password, or unsubscribe from this list, visit
https://www.eclipse.org/mailman/listinfo/jakarta.ee-spec.committee

Back to the top