fiddle-de-dee May 24 2021 at 16:10

Asciidoc для ЕСКД

7 min

12K

Введение

В этой статье хочу рассмотреть возможности 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-sostavleniya: Москва

Здесь и далее для обозначения идентификаторов используется транслитерация, ГОСТ 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 в данном случае — идентификатор сноски, если необходимо поместить её более, чем в одном месте.

Выводы

Asciidoc позволяет создавать документацию в соответствии с требованиями ЕСКД.
Синтаксис Asciidoc не сложнее самого ГОСТ Р 2.105—9.
Можно забыть о стилях MS Word и сконцентрироваться на содержании
создаваемых документов.

Tags:

Hubs:

Technical Writing