Asciidoc для генерации отчётов к лабораторным работам
Asciidoc. Что это вообще такое?
Asciidoc — это язык разметки текста для написания технических материалов. Он даёт инструменты для сборки документов в разных форматах, включая HTML и PDF. Написан на Ruby и позволяет настраивать генерацию документов множеством способов.
Мой опыт
Word для меня неудобен, так как настройка шаблонов в нём довольно неочевидна и он требует подгонять стили для каждого абзаца отдельно.
Поэтому я для себя сам собрал шаблон для Asciidoc максимально приближенный к ГОСТ 7.32-2017 (Отчёт по научно-исследовательской работе), написал скрипт на Powershell, который собирает отчёт в PDF. Документы редактирую в Visual Studio Code с плагином Asciidoctor.
Шаблон доступен на Github.
Установка Asciidoc
Для Windows я использую Chocolatey. Это удобный консольный менеджер пакетов и приложений. Инструкции по установке здесь
Затем, в терминале с правами администратора, выполните:
Затем в терминале без прав администратора:
Чтобы убедиться, что установка прошла успешно, выполните
Настройка шаблона
Создайте файл template.adoc
в какой-нибудь папке (файл общий для всех документов), и вставьте туда это:
Скрипты, изменяющие логику рендера
Эти скрипты удобно разместить рядом с шаблоном из предыдущего раздела в папке custom
Титульная страница
Этот скрипт заменяет стандартную титульную страницу на корректную, согласно ГОСТу 7.32
Подпись приложения
В теме по умолчанию после номера приложения стоит двоеточие. ГОСТ этого не позволяет, поэтому напишем скрипт, который уберёт двоеточие:
Подпись рисунка
Аналогично заменим точку после номера рисунка на длинное тире:
Тема
Настроим шрифты, отступы и прочие стили согласно ГОСТу. Это yml файл, который нужно положить в resources/themes/report-theme.yml
Шрифты
Затем скачайте шрифты Times New Roman и Jetbrains Mono (есть в репозитории) и разместите их в папке resources/fonts
Документ
Скрипт, который я приведу ниже, предполагает что файл документа называется report.adoc
. В этом файле будем писать разметку документа. Шпаргалка по синтаксису.
Скрипт запуска
Для генерации отчёта используется скрипт на powershell, который я кладу в папку scripts
рядом с документом. <путь-до-папки-с-шаблоном>
нужно заменить на фактический путь до ресурсов шаблона.
После запуска этого скрипта на выходе получим файл номер-группы-название-предмета-номер-работы-фамилия-автора.pdf
.
Вывод
Для меня asciidoc стал удобным инструментом быстрого написания красивых отчётов лабораторных работ для универа. В этой статье я поделился своим опытом организации процесса создания таких отчётов и готовым шаблоном, максимально приближенным к ГОСТ 7.32-2017