Введение

В этой статье хочу рассмотреть возможности Asciidoc в части обеспечения требований соответствия документов требованиям единой системы конструкторской документации (ЕСКД), конкретно ГОСТ Р 2.1059 (далее ГОСТ ЕСКД). Почему именно 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+|Заголовок графы 12+|Заголовок графы 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]....@startumlrectangle "Компонент 1" as c1rectangle "Компонент 2" as c2rectangle "Компонент 3" as c3c1 <-> c2c1 .. c3c2 == 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.1059.

   
   

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