Введение

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

Пакет Версия
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
asciidoc 10.2.0
asciidoctor 2.0.18

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

Установка Ruby

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

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

  2. Обновите кеш APT:

     sudo apt update

  3. Установите Ruby, его зависимости, инструменты сборки (нужны для нативной сборки некоторых библиотек) и заголовочные файлы:

     sudo apt install \
    build-essential \
    libedit-dev \
    libffi-dev \
    libssl-dev \
    libyaml-dev \
    ruby-dev \
    ruby-full

  4. Установите Bundler:

     sudo gem install bundler

Настройка Bundler

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

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

  2. В корневом каталоге проекта выполните команду инициализации:

     bundle init

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

     # frozen_string_literal: true

 source 'https://rubygems.org'

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

  4. Настройте Bundler:

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

       bundle config set deployment false

    2. Укажите путь к каталогу для хранения гемов.

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

       bundle config set path .bundle/gems

  5. Установите гемы:

     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