0033 — AsciiDoc в Debian Bookworm

17 июл. 2023

Введение

В Debian Bookworm добавили несколько пакетов для поддержки AsciiDoc:

Пакет

Версия

asciidoc

10.2.0

asciidoc-base

10.2.0

asciidoc-common

10.2.0

asciidoc-dblatex

10.2.0

asciidoc-fop

10.2.0

asciidoc-tests

10.2.0

asciidoctor

2.0.18

В использовании этих пакетов вижу проблему: они привязаны к версии Debian и не будут обновляться. Ну разве что там выявят проблемы безопасности. Такова политика релизов Debian. По этой причине целесообразно установить Ruby, но без пакетов AsciiDoc.

Установка Ruby

Удалите пакеты Debian, если они установлены:

sudo apt purge \
   asciidoc \
   asciidoc-base \
   asciidoc-common \
   asciidoc-dblatex \
   asciidoc-fop \
   asciidoc-tests \
   asciidoctor

Обновите кеш APT:
```
sudo apt update
```
Установите Ruby, его зависимости, инструменты сборки (нужны для нативной сборки некоторых библиотек) и заголовочные файлы:
```
sudo apt install \
   build-essential \
   libedit-dev \
   libffi-dev \
   libssl-dev \
   libyaml-dev \
   ruby-dev \
   ruby-full
```
Установите Bundler:
```
sudo gem install bundler
```

Настройка Bundler

Настройте ваш проект на работу с Bundler:

Если в корневом каталоге проекта уже есть Gemfile, переместите его куда-нибудь в другое место, иначе не получится инициализировать Bundler.
В корневом каталоге проекта выполните команду инициализации:
```
bundle init
```

Заполните созданный Gemfile, например:

# frozen_string_literal: true

source 'https://rubygems.org'

gem 'asciidoctor'
gem 'asciidoctor-pdf'
gem 'pygments.rb'

Настройте Bundler:
1. Выберите режим работы в Production:

bundle config set deployment false

Укажите путь к каталогу для хранения гемов. По умолчанию они хранятся в одном из подкаталогов домашнего каталога, но мне больше нравится, когда они хранятся в каталоге проекта:

bundle config set path .bundle/gems

Установите гемы:
```
bundle install
```

Сборка

Для сборки проекта вызовите команду asciidoctor или asciidoctor-pdf, но не напрямую, а с помощью Bundler:

bundle exec asciidoctor-pdf <параметры>

Я использую Makefile такого вида:

CC = bundle exec asciidoctor-pdf \
		--attribute pdf-fontsdir="src/fonts/;GEM_FONTS_DIR" \
		--attribute pdf-theme=white \
		--attribute pdf-themesdir=src/themes/ \
		--backend pdf \
		--destination-dir=./build/ \
		--failure-level "INFO" \
		--source-dir=./src/ \
		--verbose \
		--warnings

BOOK = gnu-emacs-for-technical-writers
DATE = $(shell date +%Y-%m-%d)

build-pdf:
	${CC} --out-file="${BOOK}" ./src/index.adoc


white: $(theme)
	${CC} --out-file="$(BOOK)-$(DATE).pdf" ./src/index.adoc

monokai:
	${CC} --attribute pdf-theme=monokai --out-file="$(BOOK)-$(DATE)-monokai.pdf" ./src/index.adoc

.PHONY: clean
clean:
	rm build/*.*

Обновление

Выполнять обновление можно только если у вас не-продуктовое окружение (значение упомянутого выше параметра production равно false). Чтобы обновить гемы, выполните в каталоге проекта команду:

bundle update