some experiences with the asciidoctor-toolchain / vagrant

Hi,

For the upcoming academic year, I -as a lecturer- converted my course materials to Asciidoctor. (it's a course on computer architecture, written in Dutch if you would be interested ;-) )
The resulting pdf is about 150 pages, including lots of images, stem, ..
I used asciidoctor before for smaller documents, but if someone would be looking for a heavier document to test some edge cases in asciidoctor, this could help...
The source of the document is in a repository at: https://github.com/roelvs/computerarchitectuur
The resulting files are here:
(pdf) http://roelvansteenberghe.ikdoeict.be/cursus/book_comparch.pdf
(html) http://roelvansteenberghe.ikdoeict.be/cursus/book_comparch.html


Some of my experiences on the conversion:

* Overall I am quite happy with the result. The pdf looks clean (een in the current alpha phase of the asciidoctor-pdf gem), but there are still some imperfections (although most of them are already covered in the asciidoctor-pdf beta1 milestone)
** including utf-8 'special' characters is a challenge: the pdf convertor crashes when using a fallback font. What am I doing wrong here?
** footnotes are quite useless now, so I removed most of them. (for example, it makes my tables explode if they are rendered inline instead of on the end of a page/chapter in the pdf)
** No idea why, but a toc does not show up in the pdf...
** using relative paths and 'include' files drove me crazy. I use a main book document and subdocuments with images in subfolders, but asciidoctor-pdf couldn't resolve the image paths. (but asciidoctor can) I switched to absolute image paths as a workaround, but this ..well... suboptimal. Maybe the different parsers should be aligned a little better to provide a consistent parsing of directories/files? for details, see https://github.com/asciidoctor/asciidoctor-pdf/issues/93
* building the asciidoctor-mathematical (for the STEM formulas) was a challenge because of a lot of package dependencies. To save myself (and others) that effort in the future, I created a Vagrantfile for the Asciidoctor toolchain, inspired on the existing Dockerfile. Feel free to use this vagrant image to use all the latest and greatest features of the asciidoctor toolchain without loosing time figuring out dependencies. The Vagrantfile is hosted on https://github.com/roelvs/asciidoctor-vagrant.  The vagrant machine is based on the cloud image of Fedora 22.


In a next phase I would like to automate the building process so that every commit results in a new build. I could hack together a few shell scripts to do this in combination with a push hook, but I'm sure there are some better suggestions... What would you 'as a community' recommend?

Keep up the good work!

I had also opened a thread on this forum to share feedback I got from my team on the PDF output produced by asciidoctor. I think it is valuable feedback. Thanks for sharing.

roelvs wrote

** footnotes are quite useless now, so I removed most of them. (for example, it makes my tables explode if they are rendered inline instead of on the end of a page/chapter in the pdf)

The open issue for this is:
https://github.com/asciidoctor/asciidoctor-pdf/issues/85

roelvs wrote

** No idea why, but a toc does not show up in the pdf...

I have no problem to have a toc in both my PDF and HTML output...
How do you build your book? Isn't the toc property set to something else there? See this thread:
http://discuss.asciidoctor.org/Is-toc-broken-in-1-5-0-td2095.html
I build with maven, and I know that I have defined the toc value in the pom.xml (if I try to do it somewhere else, it is too late)...

Hi,

I took the liberty to mention you on the "Who's Using Asciidoctor" issue:
https://github.com/asciidoctor/asciidoctor.org/issues/270#issuecomment-139119482

Please let a feedback if you do not agree with it.