I wrote a book and chose Asciidoctor, because it's got a lot of built-in features for writing technical docs, such as 'admonitions' (the "tip", "warning", "info" blocks, etc.), 'sidebars' (the boxed Q&A/ancillary blocks you often see in technical books) and code syntax highlighting, with per-line 'callouts' (i.e. you can write explanations of what each line in a sample code block is doing). It can also generate images from ASCII diagrams, but I didn't get amazing results, so I created my own diagrams as SVGs in draw.io.
It's easy to render PDF and EPUB, and Asciidoc syntax is not much of a jump from Markdown either. The biggest challenge is learning the correct name of the typesetting feature that you need, so you know what to look for in the Asciidoctor reference. :-)
So my process was as follows:
1. 1 "parent" Asciidoc manuscript, with individual chapters written in separate files and included with "include::"
2. Write sample code, marking each code block with Asciidoctor fencing, and then reference each code block from the manuscript. Asciidoctor will then include the code and add syntax highlighting etc. I also try to write the example code inside unit tests, so it can be tested every time the book is built.
3. Wrap the process in some sort of build tool. I chose Maven (there's an Asciidoctor plugin for Maven). The process builds the book PDF/EPUB, tests the book sample code, and builds any associated artifacts (like an example .zip file).
Now I'm writing a new short book, and this time I'm trying out Pandoc->PDF (via LaTeX). The learning curve is pretty steep, and the LaTeX errors are a bit WTF, but the eisvogel template (as also recommended by asicsp in this thread) is a great way to have something presentable very quickly.
It's easy to render PDF and EPUB, and Asciidoc syntax is not much of a jump from Markdown either. The biggest challenge is learning the correct name of the typesetting feature that you need, so you know what to look for in the Asciidoctor reference. :-)
So my process was as follows:
1. 1 "parent" Asciidoc manuscript, with individual chapters written in separate files and included with "include::"
2. Write sample code, marking each code block with Asciidoctor fencing, and then reference each code block from the manuscript. Asciidoctor will then include the code and add syntax highlighting etc. I also try to write the example code inside unit tests, so it can be tested every time the book is built.
3. Wrap the process in some sort of build tool. I chose Maven (there's an Asciidoctor plugin for Maven). The process builds the book PDF/EPUB, tests the book sample code, and builds any associated artifacts (like an example .zip file).
Now I'm writing a new short book, and this time I'm trying out Pandoc->PDF (via LaTeX). The learning curve is pretty steep, and the LaTeX errors are a bit WTF, but the eisvogel template (as also recommended by asicsp in this thread) is a great way to have something presentable very quickly.