# Pandoc Background

I have been writing books and documentation using Pandoc. With Pandoc you typically use a flavor of Markdown. Generating a book is like this:

❯ pandoc --defaults pdf-settings.txt
output-file:   sample-julia-beginners.pdfstandalone:    true# Gets put in LaTeX header of intermediate latex document created.include-in-header: header.tex# Need to use this PDF engine to support Unicodepdf-engine: xelatexinput-files:- title.txt- preface.md- intro.md

# Enter AsciiDoc

AsciiDoc in contrast is nothing like that. That was confusing to me at first, because I kept looking for a description of the configuration file that said how my book configured and what files it was made out of.

include::ch01-hello.adoc[]include::ch02-numbers.adoc[]include::ch03-strings.adoc[]
:leveloffset: 1:xref::xrefstyle: short:stem: latexmath:source-highlighter: coderay:bibliography-database: dl4nlp.bib
:chapter: 2:sectnumoffset: 1

# AsciiDoc Flexibility

Compared to Pandoc Markdown AsciiDoc feels like a more complete solution. It has support for a lot more stuff. The downside is getting all this to work is tricker. Pandoc feels more like a big comprehensive package which solves everything out of the box.

[[Listing-XYZ-1, reftext={chapter}.{counter:listing}]].Listing title[source,python]----print("Hello world") <1>----<1> Say hello

# Avoid Ruby Configuration Hell

The price you got to pay for all of these features and flexibility is what felt like configuration hell. To be fair I was probably a bit unlucky and mix Ruby skills are rusty.

$gem install asciidoctor-pdf ERROR: While executing gem ... (NoMethodError) undefined method request' for nil:NilClass ❯ gem install --pre asciidoctor-pdf # Installing and Using RVM rvm is software to manage multiple versions of Ruby. By using rvm we can switch to e.g. the latest 2.x version of Ruby, Ruby 2.7.3 to install asciidoctor-pdf. ❯ brew install gnupg ❯ gpg --keyserver hkp://pool.sks-keyservers.net --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3 7D2BAF1CF37B13E2069D6956105BD0E739499BDB ❯ \curl -sSL https://get.rvm.io | bash ❯ rvm use defaultRVM is not a function, selecting rubies with 'rvm use ...' will not work. ❯ rvm install 2.7.3 ❯ rvm list=* ruby-2.7.3 [ x86_64 ]# Default ruby not set. Try 'rvm alias create default <ruby>'. ❯ rvm alias create default 2.7.3 ❯ zsh --login ❯ bash --login ❯ rvm use default ❯ rvm list=* ruby-2.7.3 [ x86_64 ]# => - current# =* - current && default# * - default # Installing asciidoctor-pdf Now with RVM and version 2.7.3 you can install asciidoctor-pdf using gem: ❯ gem install asciidoctor-pdf ❯ which asciidoctor-pdf~/.rvm/gems/ruby-2.7.3/bin/asciidoctor-pdf # Configure Asciidoctor for Your Writing When generating PDF files using Asciidoctor you might want to use particular themes, fonts and configurations. You can add your own custom stuff under the gem install folder for asciidoctor-pdf. We have already figured out that on my Mac this is at: ~/.rvm/gems/ruby-2.7.3/ ❯ tree -L 2 ~/.rvm/gems/ruby-2.7.3/├── gems│ ├── Ascii85-1.1.0│ ├── afm-0.2.2│ ├── asciidoctor-2.0.12│ ├── asciidoctor-pdf-1.5.4│ ├── concurrent-ruby-1.1.8│ ├── css_parser-1.9.0│ ├── hashery-2.1.2│ ├── pdf-core-0.7.0│ ├── pdf-reader-2.4.2│ └── ttfunk-1.5.1 ❯ tree -L 2 ~/.rvm/gems/ruby-2.7.3/gems/asciidoctor-pdf-1.5.4├── bin│ ├── asciidoctor-pdf│ └── asciidoctor-pdf-optimize├── data│ ├── fonts│ └── themes├── docs│ └── theming-guide.adoc└── lib ├── asciidoctor ├── asciidoctor-pdf └── asciidoctor-pdf.rb extends: defaultfont: merge: true catalog: Noto Serif: normal: GEM_FONTS_DIR/notoserif-regular-subset.ttf bold: GEM_FONTS_DIR/notoserif-bold-subset.ttf bold_italic: GEM_FONTS_DIR/notoserif-bold_italic-subset.ttfpage: margin: [0.67in, 0.67in, 0.67in, 0.67in] size: Letter ❯ tree -L 3 ~/.rvm/gems/ruby-2.7.3/gems/asciidoctor-pdf-1.5.4├── data│ ├── fonts│ └── themes│ ├── base-theme.yml│ ├── default-theme.yml│ ├── default-with-fallback-font-theme.yml│ └── manning-theme.yml # LaTeX Math Does Not Work! Here there can be a lot of problems. I made a serious of mistakes here which I hope others can learn from and avoid. ## Notation for Formatting LaTeX Math Let me start from the first embarrassing mistake. I thought you wrote Math like this because that is what all Markdown flavors do: $$k_{n+1} = n^2 + k_n^2 - k_{n-1}$$ [latexmath]++++k_{n+1} = n^2 + k_n^2 - k_{n-1}++++ :stem: latexmath [stem]++++x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}++++ Inline equation works too! latexmath:[a^2+b^2=c^2]. Or as stemstem:[a^2+b^2=c^2]. Pretty nice, huh? ## Add LaTeX Support To actually produce math equations in HTML or PDF you need to add support for this. ❯ gem install asciidoctor-mathematical ❯ asciidoctor-pdf -a pdf-style=manning -r asciidoctor-mathematical math-sample.adoc ## Get Fonts Right! If your LaTeX math looks bad it may not be because of problems with your installation of configuration but rather that you lack appropriate fonts. Here is an example from bad output I got: ❯ tree -L 2 ~/.rvm/gems/ruby-2.7.3/gems/asciidoctor-pdf-1.5.4├── data│ ├── fonts│ └── themes # Wrong Advice on Fonts! This is an edit to original story cd ~/Library/Fontscurl -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/cmex10.ttf \ -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/cmmi10.ttf \ -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/cmr10.ttf \ -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/cmsy10.ttf \ -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/esint10.ttf \ -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/eufm10.ttf \ -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/msam10.ttf \ -LO http://mirrors.ctan.org/fonts/cm/ps-type1/bakoma/ttf/msbm10.ttf # Testing Mathematical if You Are Unsure If you are not sure where the problem is, then you can test the mathematical Ruby Gem directly. require 'mathematical'r = Mathematical.newFile.open("mathy.svg", "w") {|f| d = r.render("$f(x) = x\$")     f.write(d[:data])}`

Geek dad, living in Oslo, Norway with passion for UX, Julia programming, science, teaching, reading and writing.

## More from Erik Engheim

Geek dad, living in Oslo, Norway with passion for UX, Julia programming, science, teaching, reading and writing.

## Takeaways from building and deploying my first machine learning web app!

Get the Medium app