В этой статье хочу рассмотреть возможности Asciidoc в части обеспечения требований соответствия документов требованиям единой системы конструкторской документации (ЕСКД), конкретно ГОСТ Р 2.105—9 (далее ГОСТ ЕСКД). Почему именно Asciidoc, я писал здесь. Сразу уточню. Вопрос форматирования документа здесь не рассматривается. Создающий документацию не должен задумываться о форматировании. Как системный аналитик я создаю содержание и контролирую его структуру. Для получения документа, соответствующего ГОСТ ЕСКД или другому аналогичному стандарту, я должен нажать кнопку и получить корректно отформатированный документ в любых требуемых вариантах: pdf, Open Document (Libre
Office/Open Office), Open XML (Microsoft Word) и прочих. После работы над https://github.com/CourseOrchestra/asciidoctor-open-document уверен,
что все проблемы форматирования решаются адекватными усилиями.  Рассмотрим структуру документа Asciidoc, соответствующего требованиям
ГОСТ ЕСКД. В пункте 6.1.1 ГОСТ ЕСКД приведена рекомендуемая структура, которую в Asciidoc можно отобразить следующим образом. Обратите внимание: здесь нет раздела «титульный лист», он определяется настройками форматирования. В титульном листе, как минимум, должно присутствовать наименование документа, а также другие атрибуты: автор, место составления (издания), год составления (издания) и т.п. Эти атрибуты задаются прямо в документе. Здесь и далее для обозначения идентификаторов используется транслитерация, ГОСТ 7.79-2000 (система Б). Разработчики данного ГОСТ совершили лёгкое вредительство, не позволяющее использовать его для идентификаторов, поэтому мы используем доработанную версию, подробности здесь. Для некоторых атрибутов предусмотрен упрощенный синтаксис, в данном случае наименование документа вводится первой строкой после одного знака =. Раздел с содержанием (подраздел 6.2 ГОСТ ЕСКД) заполняется автоматически при генерации документации. Разделы «Приложение» (подраздел 6.3 ГОСТ ЕСКД), «Библиография» (подраздел 6.4. ГОСТ ЕСКД) и «Предисловие» определены специальными ключевыми словами: preface даст возможность процессору Asciidoctor понять, что не
нужно включать этот раздел в содержание; appendix позволит автоматически нумеровать приложения буквами; bibliography объявляет раздел с библиографическими ссылками
документа. Встроенная поддержка библиографии реализована совсем просто, для соответствия ГОСТ ЕСКД необходимо использовать расширение [asciidoctor-bibtex] https://github.com/asciidoctor/asciidoctor-bibtex). Список литературы задаём в файле формата BibTeX. В самом документе необходимо использовать следующий синтаксис. Требования к делению документов на части определены в подразделе 6.5 ГОСТ ЕСКД. Для деления документа на разделы/подразделы/пункты используется синтаксис: Атрибут secnums задаёт нумерацию разделов полностью по ГОСТ ЕСКД. Чтобы Asciidoc отличал пункт от заголовка раздела (особенно, если пункт не имеет заголовка) можно использовать специальную роль, например [.punkt]. Роль задаём над заголовком. Требования к перечислениям определены в подразделе 6.7 ГОСТ ЕСКД. В Asciidoc перечисления задаются так: Обратите внимание: у перечисления может быть наименование. В ГОСТ ЕСКД такого понятия нет, но Asciidoc позволяет в печатном документе не отрывать наименование от перечисления. В некоторых случаях это можно использовать. Можно включать в список дополнительные абзацы, графику и иное содержание. Для этого используют символ +. В ГОСТ ЕСКД возможно маркировать первый уровень перечислений дефисом. Для этого приведённый пример переоформим следующим образом. Asciidoc допускает вложенность пунктов до пятого уровня. В качестве примера рассмотрим таблицу, приведённую на рисунке 1 ГОСТ ЕСКД (пункт 6.8.1). Результат зависит от настроек форматирования. Заданная выше таблица будет выглядеть приблизительно следующим образом.  Наименование таблицы, как и наименование любых других элементов, вводим через символ «точка». Номер таблицы должен проставляться автоматически в соответствии с правилами форматирования. В атрибуте cols (cols = "2,1,1,1,1") указано, что в таблице будет 5 колонок, причём первая будет в два раза больше остальных. В атрибуте hrows указано количество строк в шапке таблицы. Шапка в соответствии с требованиями ГОСТ ЕСКД отображается на каждой странице, если таблица занимает более одной страницы. Атрибут hrows не поддерживается исходным процессором Asciidoctor и требует специального расширения, в данном случае https://github.com/CourseOrchestra/asciidoctor-plugins. По умолчанию поддерживается только параметр options="header", предполагающий, что
строка заголовка может быть только одна. В ГОСТ ЕСКД есть требование помещать слова «Продолжение таблицы» с указанием номера (обозначения) таблицы в начале каждой странице, на которую переносится таблица. Однако пункт 6.8.7 ГОСТ ЕСКД разрешает не указывать эту надпись при подготовке документа с использованием программных средств. В самой таблице каждая ячейка начинается с вертикальной черты (|). Обычно между строками таблицы делают дополнительный перенос строки, так с таблицей легче работать. Первая ячейка таблицы занимает по вертикали место двух ячеек, поэтому использован синтаксис .2+|. Заголовки граф занимают две ячейки по горизонтали, использован аналогичный синтаксис, но без точки: 2+|. Для размещения графического материала (подраздел 6.9 ГОСТ ЕСКД) используем следующий синтаксис: Нумерация рисунков, как и в случае с таблицами делается автоматически. Если изображение расположено внутри текста, то вместо двух двоеточий необходимо указать одно. Атрибуты изображения необходимы, чтобы указать, как картинка должна отображаться в документе. Можно воспользоваться имеющимися атрибутами или реализовать свои. Например, одной из основных проблем при расположении картинок в печатных документах является автоматический подбор их размера. Скажем, ваша диаграмма вытянута по вертикали. Вы добавили вниз еще один элемент, и картинка вылетела за пределы страницы. Или вы добавили элемент справа, который прекрасно влезает по ширине, но неумолимый алгоритм уверен, что главное не менять ширину и уменьшает пропорции картинки, что ведёт к мелким шрифтам и плохой читаемости. Когда я писал конвертер в Open Document, то решил это добавлением специальных свойств, контролирующих оптимальное расположение. В общем случае проблему придётся решать для каждого выходного формата. Правда, всего один раз. В отличие от использования MS Word, где подгонка каждой картинки лежит на плечах пользователя. Для процессора Asciidoctor реализовано расширение Asciidoctor Diagram для внедрения непосредственно в текст диаграмм, графиков и других элементов. Для таких диаграмм используют следующий синтаксис. Результат должен выглядеть следующим образом:  Оформляют такие диаграммы также, как обычные изображения. Работа с формулами (подраздел 6.10 ГОСТ ЕСКД) аналогична работе с диаграммами: формулы можно задать прямо в тексте. В следующем примере формула задана на языке LaTeX/Mathematics: Часто формулы имеют пояснения. Чтобы указать Asciidoc, что абзац является именно пояснением к формуле, необходимо присвоить ему какую-то роль, например. Ключевое слово stem означает, что формула помещена внутри текстовой строки. Обратите внимание на символ + в конце строки. Он означает перенос текста на другую строку без завершения абзаца. Аналогично реализуются другие элементы с фиксированным форматированием: примечания, примеры и т.п. Роль можно присваивать как отдельному абзацу, так и более крупному фрагменту текста. Ссылки (подраздел 6.11 ГОСТ ЕСКД) в Asciidoc реализованы так: каждому объекту, на который необходима ссылка, присваивают идентификатор. Например, идентификатор для картинки может быть задан в удвоенных парных квадратных скобках: Для ссылки на данную диаграмму используем следующий синтаксис. В этом случае текст в документе будет выглядеть так: Для html-варианта (например, в интерактивной справке) можно вместо текста «рисунок 1» отображать его название. Не очень красивым выглядит то, что в тексте документа слово «рисунок» повторяется дважды. Но это самый простой вариант, который позволяет с одной стороны соответствовать ГОСТ ЕСКД, а с другой — сохранять падежи при использовании автоматизированной генерации документов. Для сносок (подраздел 6.13 ГОСТ ЕСКД) в Asciidoc существует специальный синтаксис. f1 в данном случае — идентификатор сноски, если необходимо поместить её более, чем в одном месте. Asciidoc позволяет создавать документацию в соответствии с требованиями ЕСКД. Синтаксис Asciidoc не сложнее самого ГОСТ Р 2.105—9. Можно забыть о стилях MS Word и сконцентрироваться на содержании
создаваемых документов. Системный аналитик