Примечания, основанные на моей борьбе с настройкой AsciiDoc с математической поддержкой латекса.

Вы не можете заставить AsciiDoc делать то, что вы хотите? Вы боретесь с правильной настройкой Ruby, чтобы AsciiDoc делал то, что вы хотите? Вы спрашиваете себя, почему AsciiDoc больше не похож на Markdown?

Тогда у вас было много таких же проблем, как и у меня. Поэтому я постараюсь передать решения проблем и заблуждений, которые у меня были, пока они еще свежи в памяти.

Фон Pandoc

Я писал книги и документацию, используя Pandoc. С Pandoc вы обычно используете разновидность Markdown. Создание книги выглядит так:

❯ pandoc --defaults pdf-settings.txt

Таким образом, с Pandoc у вас есть большая часть вашей конфигурации в файле, который внутри выглядит примерно так:

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

Специфика здесь не так уж и важна. На самом деле я просто хотел сказать, что с Pandoc вы пишете свою книгу как состоящую из нескольких файлов, которые сшиваются вместе с помощью файла конфигурации.

Мой опыт работы с Pandoc: Советы по написанию электронной книги.

Введите AsciiDoc

AsciiDoc, напротив, не имеет ничего подобного. Сначала это сбивало меня с толку, потому что я продолжал искать описание файла конфигурации, в котором говорилось, как настроена моя книга и из каких файлов она была сделана.

В этом отношении AsciiDoc более знаком с LaTeX. Вы в основном пишете один документ, но этот документ может ссылаться на другие файлы, если вы хотите разделить его. В отличие от Markdown, вы можете создавать ссылки в файлах где угодно.

include::ch01-hello.adoc[]

include::ch02-numbers.adoc[]

include::ch03-strings.adoc[]

И так же, как LaTeX, большая часть конфигурации, относящейся к форматированию и созданию вашего документа, хранится в заголовке самого документа. Таким образом, вы можете увидеть что-то вроде этого в начале файлов документов:

:leveloffset: 1
:xref:
:xrefstyle: short
:stem: latexmath
:source-highlighter: coderay
:bibliography-database: dl4nlp.bib

Если вы используете AsciiDoc во время сотрудничества с издателем, обратите внимание, что у него могут быть другие методы, отличные от тех, которые вы видите в официальных документах.

Например, я продолжал пытаться понять, как я собираюсь сгенерировать всю свою книгу из нескольких файлов, но после долгой борьбы понял, что издатель действительно просто заинтересован в независимой работе с главами. На самом деле в этом есть большой смысл. Если вы создадите всю книгу, вы получите один большой PDF-файл. Но люди, дающие вам обратную связь, скорее всего, захотят по одному PDF-файлу для каждой главы, а не для всей книги.

Вы можете подумать, что это испортит количество разделов, глав и т. Д., Но AsciiDoc нужно часто использовать таким образом, потому что вы можете легко настроить это для каждого документа главы. Здесь, если вы поместите это в заголовок, будет сказано, что созданный вами PDF-файл предназначен для второй главы. Нумерация разделов начинается со смещения единицы.

:chapter: 2
:sectnumoffset: 1

Гибкость AsciiDoc

По сравнению с Pandoc Markdown AsciiDoc кажется более полным решением. Он поддерживает гораздо больше вещей. Обратной стороной является хитрость, заставляющая все это работать. Pandoc больше похож на большой комплексный пакет, который решает все из коробки.

Что мне нравится в AsciiDoc, так это то, что у вас гораздо больше гибкости в том, как вы маркируете фигуры, листинги кода и т. Д. Этот пример дает заголовок коду и даже помещает маленькие пронумерованные капли рядом с определенной строкой кода.

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

Избегайте ада конфигурации Ruby

Цена, которую вы должны заплатить за все эти функции и гибкость, казалась адом конфигурации. Честно говоря, мне, наверное, немного не повезло, и навыки смешивания Ruby - ржавые.

Например, когда я попытался установить генератор PDF для asciidoctor, я получил такую ​​ошибку:

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

Причина этого в том, что, установив Ruby на моем Mac с помощью Homebrew, я теперь получаю версию 3.x, а последняя стабильная версия asciidoctor-pdf предназначена для Ruby 2.7.3.

Конечно, вы можете установить альфа-версию:

❯ gem install --pre asciidoctor-pdf

Вот только у меня не было такого опыта. Таким образом, вы быстро понимаете, что вам действительно нужно заставить RVM обрабатывать разные версии Julia. Это не так просто использовать, как с Python.

Установка и использование RVM

rvm - это программное обеспечение для управления несколькими версиями Ruby. Используя rvm, мы можем переключиться, например, на последняя версия 2.x Ruby, Ruby 2.7.3 для установки asciidoctor-pdf.

Есть несколько необычных шагов. Например. вам необходимо установить GPG, инструмент GNU для Pretty-Good-Privacy (pgp), который используется для криптографии. В частности, он, как правило, часто используется в мире с открытым исходным кодом для цифровой подписи документов и двоичных файлов.

Вы можете рассматривать его как альтернативу системе сертификатов, используемой в Интернете для HTTPS. В macOS вы устанавливаете GPG с помощью Homebrew:

❯ brew install gnupg

Теперь вы можете установить ключи GPG. Почему? Эти открытые ключи в системе шифрования с частным и открытым ключом. У GPG есть сервер, на котором размещены открытые ключи. Соответствующие закрытые ключи хранятся в секрете их владельцами. Таким образом, у создателей Ruby RVM есть закрытые ключи, которые они используют для создания цифровой подписи в дистрибутиве RVM. Получив их открытые ключи, вы можете убедиться, что вы загрузили нужную версию.

❯ gpg --keyserver hkp://pool.sks-keyservers.net --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3 7D2BAF1CF37B13E2069D6956105BD0E739499BDB

Теперь мы можем скачать rvm. Обратите внимание на использование обратной косой черты \curl. Это препятствует использованию псевдонима для curl.

❯ \curl -sSL https://get.rvm.io | bash

В этот момент я подумал, что могу использовать rvm, и ввел такие команды, как:

❯ rvm use default

RVM is not a function, selecting rubies with 'rvm use ...' will not work.

За исключением того, что я получил запутанное сообщение об ошибке, показанное выше. Но мы все еще можем установить последнюю версию Ruby 2. *:

❯ 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

Однако, чтобы иметь возможность переключаться между различными версиями Ruby и избегать раздражающего сообщения об ошибке, показанного ранее, нам необходимо войти в новую оболочку. Я делаю это с помощью:

❯ zsh --login

Но если вы используете bash, вы можете использовать:

❯ bash --login

Я лично использую Fish Shell, который требует дополнительной настройки. Мое решение состояло в том, чтобы обычно переключаться на zsh для большинства этих задач по установке. После входа в оболочку вы можете написать:

❯ rvm use default

Это переключится на версию Ruby, которую вы отметили по умолчанию. Вы можете увидеть это с помощью этой команды:

❯ rvm list
=* ruby-2.7.3 [ x86_64 ]

# => - current
# =* - current && default
#  * - default

Установка asciidoctor-pdf

Теперь с RVM и версией 2.7.3 вы можете установить asciidoctor-pdf, используя gem:

❯ gem install asciidoctor-pdf

Вы можете проверить, где он установлен:

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

Настройте Asciidoctor для вашего письма

При создании файлов PDF с помощью Asciidoctor вы можете захотеть использовать определенные темы, шрифты и конфигурации. Вы можете добавить свои собственные файлы в папку установки gem для asciidoctor-pdf. Мы уже выяснили, что на моем Mac это:

~/.rvm/gems/ruby-2.7.3/

На вашем компьютере все могло быть иначе. Просто используйте which asciidoctor-pdf, чтобы выяснить, где находится каталог драгоценных камней. Вот отредактированный вывод:

❯ 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

Мы видим, что нам следует посмотреть на asciidoctor-pdf-1.5..

❯ 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

Для добавления ваших собственных настроек нас действительно интересуют папки data/fonts и data/themes. Например, если бы я работал с Manning Publishing, они могли бы предоставить мне свой собственный .yaml файл стиля с именем manning-theme.yaml. Внутри это выглядело бы примерно так. Вы можете видеть, что это расширяет тему по умолчанию, хранящуюся в default-theme.yml:

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

Вы просто скопируете этот файл в папку data/themes:

❯ 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 не работает!

Здесь может быть много проблем. Я допустил здесь серьезные ошибки, и надеюсь, что другие смогут извлечь уроки из них и избежать их.

Обозначения для форматирования математики LaTeX

Позвольте мне начать с первой досадной ошибки. Я думал, что вы написали математику так, потому что это то, что делают все разновидности Markdown:

$$
k_{n+1} = n^2 + k_n^2 - k_{n-1}
$$

Но в Asciidoc вы пишете это так:

[latexmath]
++++
k_{n+1} = n^2 + k_n^2 - k_{n-1}
++++

На самом деле есть несколько способов. В заголовке вы можете определить, что следует использовать в STEM (наука, технология, инженерия, математика), с помощью этого:

:stem: latexmath

Это позволяет вам писать уравнения немного по-другому. Какая польза? Я полагаю, что позже будет проще изменить систему, которую вы используете для создания графики уравнений.

[stem]
++++
x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}
++++

Естественно, строчные уравнения тоже разные. Они написаны не как $a^2+b^2=c^2$, а как:

Inline equation works too! latexmath:[a^2+b^2=c^2]. Or as stem
stem:[a^2+b^2=c^2]. Pretty nice, huh?

Добавить поддержку LaTeX

Чтобы на самом деле создавать математические уравнения в HTML или PDF, вам необходимо добавить поддержку этого.

❯ gem install asciidoctor-mathematical

После его установки вот пример того, как я мог бы создать файл PDF:

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

Вы видите, что использование -a pdf-style=manning заставляет Asciidoctor использовать файл темы manning-theme.yml, который мы ранее хранили в папке тем.

В то время как -r asciidoctor-mathematical разрешает математическую поддержку. Если мы его не будем использовать, то вы увидите дословный код LaTeX, а не графику для уравнения.

Получите правильные шрифты!

Если ваша математика LaTeX выглядит плохо, это может быть не из-за проблем с вашей установкой конфигурации, а скорее из-за отсутствия подходящих шрифтов. Вот пример плохого вывода, который я получил:

Видеть, что квадратный корень √ неверен. Вы также столкнетесь с этой проблемой, если скобки выглядят неправильно. Например. LaTeX \left( и \right) выглядят неправильно. Как решить эту проблему?

Либо вам нужно найти это, либо ваш издатель предоставил вам шрифты, которые вы устанавливаете в папке fonts:

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

Неправильный совет по шрифтам!

Это редактирование оригинальной истории

Совет по шрифтам, который я дал, вероятно, не сработает. Видимо потому, что Mathematical, который производит математические уравнения, на самом деле не взаимодействует с asciidoctor-pdf. mathematical Ruby Gem заставляет математические уравнения создавать их в виде файлов PDF и никогда не смотрит на то, что asciidoctor-pdf использует для шрифтов. Вместо этого он использует ваши локальные шрифты. Итак, чтобы получить правильные шрифты, вам необходимо:

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

Тестирование по математике, если вы не уверены

Если вы не уверены, в чем проблема, вы можете напрямую протестировать mathematical Ruby Gem.

require 'mathematical'
r = Mathematical.new
File.open("mathy.svg", "w") {|f|
     d = r.render("$f(x) = x$")
     f.write(d[:data])
}

Теперь у вас есть файл с именем mathy.svg в текущем каталоге. Убедитесь, что скобки, корневой символ и т. Д. Выглядят нормально.