Введение

В этой статье хочу рассмотреть возможности 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 можно отобразить следующим образом.

= Наименование документа [preface] == Предисловие == Обозначения и сокращения == Термины и определения == Основное тематическое содержание документа (например, «Особенности приготовления рататуя») [appendix] == Приложения (например, «Перечень ингредиентов») == Ссылочные нормативные документы == Ссылочные документы [bibliography] == Библиография == Лист регистрации изменений

Обратите внимание: здесь нет раздела «титульный лист», он определяется настройками форматирования. В титульном листе, как минимум, должно присутствовать наименование документа, а также другие атрибуты: автор, место выпуска, год выпуска и т.п. Эти атрибуты задаются прямо в документе.

:mesto-vyhpuska: Москва

Здесь и далее для обозначения идентификаторов используется транслитерация, ГОСТ 7.79-2000 (система Б). Разработчики данного ГОСТ совершили лёгкое вредительство, не позволяющее использовать его для идентификаторов, поэтому мы используем доработанную версию, подробности здесь.

Для некоторых атрибутов предусмотрен упрощенный синтаксис, в данном случае наименование документа вводится первой строкой после одного знака =.

Раздел с содержанием (подраздел 6.2 ГОСТ ЕСКД) заполняется автоматически при генерации документации.

Разделы «Приложение» (подраздел 6.3 ГОСТ ЕСКД), «Библиография» (подраздел 6.4. ГОСТ ЕСКД) и «Предисловие» определены специальными ключевыми словами:

• preface даст возможность процессору Asciidoctor понять, что не
  нужно включать этот раздел в содержание;

• appendix позволит автоматически нумеровать приложения буквами;

• bibliography объявляет раздел с библиографическими ссылками
  документа.

Встроенная поддержка библиографии реализована совсем просто, для соответствия ГОСТ ЕСКД необходимо использовать расширение [asciidoctor-bibtex] https://github.com/asciidoctor/asciidoctor-bibtex).

Список литературы задаём в файле формата BibTeX.

@Book{viz,  author    = {Волков, А. М.},  title     = {Волшебник изумрудного города},  publisher = {Эксмордество},  year      = 1921,  address   = Москва,  lang=ru }

В самом документе необходимо использовать следующий синтаксис.

:bibtex-file: путь к файлу в формате BibTeX  В изумрудный город ведёт дорога, вымощенная желтым кирпичом cite:[viz(24)].  [bibliography] == Список использованной литературы bibliography::[]

Деление документа на части

Требования к делению документов на части определены в подразделе 6.5 ГОСТ ЕСКД. Для деления документа на разделы/подразделы/пункты используется синтаксис:

== Раздел === Подраздел ==== Пункт

Атрибут secnums задаёт нумерацию разделов полностью по ГОСТ ЕСКД.

Чтобы Asciidoc отличал пункт от заголовка раздела (особенно, если пункт не имеет заголовка) можно использовать специальную роль, например [.punkt]. Роль задаём над заголовком.

[.punkt] ==== Пункт

Перечисления

Требования к перечислениям определены в подразделе 6.7 ГОСТ ЕСКД. В Asciidoc перечисления задаются так:

.Наименование списка . Первый пункт . Второй пункт .. Подпункт второго пункта + Дополнительный абзац подпункта второго пункта . Третий пункт

Обратите внимание: у перечисления может быть наименование. В ГОСТ ЕСКД такого понятия нет, но Asciidoc позволяет в печатном документе не отрывать наименование от перечисления. В некоторых случаях это можно использовать.

Можно включать в список дополнительные абзацы, графику и иное содержание. Для этого используют символ +.

В ГОСТ ЕСКД возможно маркировать первый уровень перечислений дефисом. Для этого приведённый пример переоформим следующим образом.

.Наименование списка * Первый пункт * Второй пункт . Подпункт второго пункта + Дополнительный абзац подпункта второго пункта * Третий пункт

Asciidoc допускает вложенность пунктов до пятого уровня.

Таблицы

В качестве примера рассмотрим таблицу, приведённую на рисунке 1 ГОСТ ЕСКД (пункт 6.8.1).

.Наименование таблицы [cols="2,1,1,1,1", hrows=2] |==== .2+|Головка 2+|Заголовок графы 1 2+|Заголовок графы 2  |Подзаголовок графы 1.1 |Подзаголовок графы 1.2 |Подзаголовок графы 2.1 |Подзаголовок графы 2.2  |Заголовок боковика 1 | | | |  |Заголовок боковика 2 | | | |  |Заголовок боковика 3 | | | |  |====

Результат зависит от настроек форматирования. Заданная выше таблица будет выглядеть приблизительно следующим образом.

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

В атрибуте 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 ГОСТ ЕСКД) используем следующий синтаксис:

.Наименование рисунка image::путь к изображению[атрибуты изображения]

Нумерация рисунков, как и в случае с таблицами делается автоматически.

Если изображение расположено внутри текста, то вместо двух двоеточий необходимо указать одно.

Атрибуты изображения необходимы, чтобы указать, как картинка должна отображаться в документе. Можно воспользоваться имеющимися атрибутами или реализовать свои.

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

Когда я писал конвертер в Open Document, то решил это добавлением специальных свойств, контролирующих оптимальное расположение. В общем случае проблему придётся решать для каждого выходного формата. Правда, всего один раз. В отличие от использования MS Word, где подгонка каждой картинки лежит на плечах пользователя.

Для процессора Asciidoctor реализовано расширение Asciidoctor Diagram для внедрения непосредственно в текст диаграмм, графиков и других элементов.

Для таких диаграмм используют следующий синтаксис.

[plantuml, png] .... @startuml rectangle "Компонент 1" as c1 rectangle "Компонент 2" as c2 rectangle "Компонент 3" as c3 c1 <-> c2 c1 .. c3 c2 == c3 @enduml ....

Результат должен выглядеть следующим образом:

Оформляют такие диаграммы также, как обычные изображения.

Формулы

Работа с формулами (подраздел 6.10 ГОСТ ЕСКД) аналогична работе с диаграммами: формулы можно задать прямо в тексте. В следующем примере формула задана на языке LaTeX/Mathematics:

[latexmath] ++++ \begin{bmatrix} a & b \\ c & d \end{bmatrix}\binom{n}{k} ++++

Часто формулы имеют пояснения. Чтобы указать Asciidoc, что абзац является именно пояснением к формуле, необходимо присвоить ему какую-то роль, например.

[formula-poyasnenie] где stem:[a] -- левый верхний элемент матрицы; + stem:[b] -- правый верхний элемент матрицы; + и т.д.

Ключевое слово stem означает, что формула помещена внутри текстовой строки.

Обратите внимание на символ + в конце строки. Он означает перенос текста на другую строку без завершения абзаца.

Аналогично реализуются другие элементы с фиксированным форматированием: примечания, примеры и т.п. Роль можно присваивать как отдельному абзацу, так и более крупному фрагменту текста.

Ссылки

Ссылки (подраздел 6.11 ГОСТ ЕСКД) в Asciidoc реализованы так: каждому объекту, на который необходима ссылка, присваивают идентификатор. Например, идентификатор для картинки может быть задан в удвоенных парных квадратных скобках:

[[moya-diagramma]] .Моя диаграмма image::moya-diagramma.jpg[]

Для ссылки на данную диаграмму используем следующий синтаксис.

Моя диаграмма изображена на рисунке (<<moya-diagramma>>).

В этом случае текст в документе будет выглядеть так:

Моя диаграмма изображена на рисунке (рисунок 1).

Для html-варианта (например, в интерактивной справке) можно вместо текста «рисунок 1» отображать его название.

Не очень красивым выглядит то, что в тексте документа слово «рисунок» повторяется дважды. Но это самый простой вариант, который позволяет с одной стороны соответствовать ГОСТ ЕСКД, а с другой — сохранять падежи при использовании автоматизированной генерации документов.

Сноски

Для сносок (подраздел 6.13 ГОСТ ЕСКД) в Asciidoc существует специальный синтаксис.

Здесь расположена сноскаfootnote:f1[Текст сноски]

f1 в данном случае — идентификатор сноски, если необходимо поместить её более, чем в одном месте.

Выводы

1. Asciidoc позволяет создавать документацию в соответствии с требованиями ЕСКД.

2. Синтаксис Asciidoc не сложнее самого ГОСТ Р 2.105—9.

3. Можно забыть о стилях MS Word и сконцентрироваться на содержании
   создаваемых документов.