AsciiDoc and Ruby on macOS

Notes based on my struggles configuring AsciiDoc with latex math support.

Pandoc Background

❯ pandoc --defaults pdf-settings.txt
output-file:   sample-julia-beginners.pdf
standalone: true

# Gets put in LaTeX header of intermediate latex document created.
include-in-header: header.tex

# Need to use this PDF engine to support Unicode
pdf-engine: xelatex

input-files:
- title.txt
- preface.md
- intro.md

Enter AsciiDoc

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

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

Avoid Ruby Configuration Hell

$ gem install asciidoctor-pdf 
ERROR: While executing gem ... (NoMethodError)
undefined method `request' for nil:NilClass
❯ gem install --pre asciidoctor-pdf

Installing and Using RVM

❯ brew install gnupg
❯ gpg --keyserver hkp://pool.sks-keyservers.net --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3 7D2BAF1CF37B13E2069D6956105BD0E739499BDB
❯ \curl -sSL https://get.rvm.io | bash
❯ rvm use default

RVM 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

❯ gem install asciidoctor-pdf
❯ which asciidoctor-pdf
~/.rvm/gems/ruby-2.7.3/bin/asciidoctor-pdf

Configure Asciidoctor for Your Writing

~/.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: default
font:
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.ttf
page:
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!

Notation for Formatting LaTeX Math

$$
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 stem
stem:[a^2+b^2=c^2]. Pretty nice, huh?

Add LaTeX Support

❯ gem install asciidoctor-mathematical
❯ asciidoctor-pdf -a pdf-style=manning -r asciidoctor-mathematical  math-sample.adoc

Get Fonts Right!

❯ tree -L 2 ~/.rvm/gems/ruby-2.7.3/gems/asciidoctor-pdf-1.5.4
├── data
│ ├── fonts
│ └── themes

Wrong Advice on Fonts!

cd ~/Library/Fonts
curl -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

require 'mathematical'
r = Mathematical.new
File.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.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store