Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
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! |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
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.
The open issue for this is: https://github.com/asciidoctor/asciidoctor-pdf/issues/85 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)... |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
In reply to this post by roelvs
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. |
Loading... |
Reply to author |
Edit post |
Move post |
Delete this post |
Delete this post and replies |
Change post date |
Print post |
Permalink |
Raw mail |
Administrator
|
In reply to this post by roelvs
On Tue, Sep 8, 2015 at 7:14 AM, roelvs [via Asciidoctor :: Discussion] <[hidden email]> wrote: if someone would be looking for a heavier document to test some edge cases in asciidoctor, this could help... I looooove finding new use cases. Cloned! there are still some imperfections (in asciidoctor-pdf) No doubt, we still have some work to do. PDF is much tougher to get right than HTML, but we'll get there. including utf-8 'special' characters is a challenge: the pdf convertor crashes when using a fallback font. What am I doing wrong here? The plan for beta1 is to pack more characters into the Noto Serif font. In an ideal case, you don't want to have to use a fallback font because it's *really* slow (and could be the source of a crash because of how it works). It's much, much better to use a font that has all the characters you need. We have to strike a balance in the default theme because we don't know what language is being used (we have to cater to as many as we can). But when you know what language you are using, it is much better to use a single font that targets that language and not use the fallback font. More information about using your own fonts is mentioned here: No idea why, but a toc does not show up in the pdf... I noticed that you have blank lines in your document header. Like HTTP, your document header should have no blank lines. The document header consists of: * document title * author line (optional) * revision line (optional) * document-level attributes So it should be something like: ---- = Document Title Author Name :toc: left :sectnums: :imagesdir: images ---- Notice, no blank lines. I created a Vagrantfile for the Asciidoctor toolchain, inspired on the existing Dockerfile. Very cool! If you'd like to keep working on it, perhaps we could move it to the Asciidoctor organization. If that interests you, just let us know. Cheers, |
Free forum by Nabble | Edit this page |