[Подготовка технической документации] Asciidoc для ЕСКД

Ответить на тему

Автор

Сообщение

news_bot ^®

Стаж: 7 лет 4 месяца
Сообщений: 27286

news_bot ^® написал(а)
24-Май-2021 18:31

Цитировать

Введение
В этой статье хочу рассмотреть возможности 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 (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 и сконцентрироваться на содержании
создаваемых документов.

===========
Источник:
habr.com
===========
Похожие новости:

Теги для поиска: #_podgotovka_tehnicheskoj_dokumentatsii (Подготовка технической документации), #_eskd (ЕСКД), #_asciidoc, #_dokumentatsija (документация), #_podgotovka_tehnicheskoj_dokumentatsii (
Подготовка технической документации
)

Профиль ЛС

Ответить на тему

Вы не можете начинать темы
Вы не можете отвечать на сообщения
Вы не можете редактировать свои сообщения
Вы не можете удалять свои сообщения
Вы не можете голосовать в опросах
Вы не можете прикреплять файлы к сообщениям
Вы не можете скачивать файлы

Текущее время: 17-Июн 00:19
Часовой пояс: UTC + 5