Адаптация документов к требованиям ГОСТ с помощью MadCap Flare 12

09.11.2016

Оформить документ по ГОСТ автоматически? В MadCap Flare — легко! Представляем вашему вниманию статью Павла Сапожникова, профессионального технического писателя, активно использующего в своей работе современные технологии документирования. Данная статья посвящена оформлению комплектов документов по российским стандартам в MadCap Flare, при этом изложенные в ней рекомендации могут по аналогии применяться и в других современных профессиональных инструментах для документирования.

Большинство софтверных компаний российского IT-рынка придерживаются собственного корпоративного стиля оформления документации на разрабатываемые программные продукты. Кажется, что строгие конструкторские рамки, шрифт Times New Roman, и прочие требования ГОСТ уже давно канули в лету. Да и у современного пользователя вид User Guide, оформленного по всем канонам ГОСТ19 и ГОСТ34, вызовет разве что недоумение.

Тем не менее, российский IT-рынок специфичен и местами консервативен. Здесь до сих пор встречается требовательный заказчик в лице государственных структур, для которого приходится соблюдать некоторые нормы ГОСТ.

В данной статье проводится краткий обзор возможностей MadCap Flare 12, которые позволяют адаптировать существующий корпоративный стиль документов под требования ГОСТ.

Для начала рассмотрим шаблон руководства пользователя в корпоративном стиле, который будем адаптировать:

• первый лист – титульный (фирменные цвета, название программного продукта, тип документа, общее количество страниц);
• второй лист – лист копирайта, где обычно излагается информация о компании и условиях использования документа;

• третий лист – содержание документа;
• начиная с четвертого листа – основной текст документа, разбитый на разделы и пункты;
• каждый новый раздел начинается с интро-листа, включающего синопсис раздела и мини-содержание раздела в виде гиперссылок.

Далее показан стиль оформления различных элементов документа.

• шрифт основного текста Arial Narrow 12;
• красные строки не используются;
• есть верхний колонтитул с названием документа и текущего раздела;
• заголовки, рисунки и таблицы не нумеруются;
• в перекрестных ссылках указывается номер целевой страницы;
• перекрестные ссылки оформлены по подобию гипертекстовых ссылок (синие и с подчеркиванием);
• определение терминов и сокращений приводится на текущем листе, в сносках.

Далее рассмотрим требования к структуре документов, которые выставил заказчик:

• на всех листах документа должны быть рамки (одного из трех типов);

• документ должен начинаться с титульного листа (рамка I типа), который содержит следующие элементы:
  • блоки для всех заинтересованных подписантов со стороны исполнителя и заказчика (должность, предприятие, имя, подпись и дата);
  • название программного продукта;
  • тип документа;
  • код документа по ГОСТ 34.201-89;
  • суммарное количество листов документа;
  • год;
  • инвентарный номер и дата сборки документа;
• второй лист — содержание (рамка II типа). В графах рамки:
  • имя разработчика, проверяющего, утверждающего и нормоконтролера;
  • название программного продукта;
  • название документа;
  • текущий лист и общее количество листов;
  • код документа по ГОСТ 34.201-89;
  • инвентарный номер и дата сборки документа.
• третий лист — термины и сокращения (рамка III типа). В рамке:
  • код документа в соответствии с ГОСТ 34.201-89;
  • текущий лист;
  • инвентарный номер и дата сборки документа.
• далее и до конца документа на листах используются только рамки III типа;
• документ должен завершаться листом регистрации изменений.

Проанализировав структурные требования, приступаем к адаптации проекта Flare.

Для начала потребуется новый набор переменных (Variables Set). В переменных удобно хранить информацию о подписантах документа и прочие сведения, которые требуются для ГОСТ-стиля.

Когда Variables Set подготовлен, можно приступать к созданию нового макета (Page Layout по терминологии Flare). В макете нужно настроить страницы трех типов (три типа рамок). Внутри макета титульного листа располагаются блоки Decoration Frame, которые содержат рамки и переменные из ранее созданного Variables Set. Таким образом при построении документа в рамки будут попадать значения переменных из Variables Set.

Ниже показаны получившиеся макеты для страниц с рамками I и III типов.

С помощью набора условных тегов (Condition Tag Set) можно включать/исключать различные элементы документа (листы, топики, отдельные теги) из той или иной сборки документа.

Нужно создать новый Condition Tag Set, который будет содержать два условных тега: ForGost и Norm.

Структура документа содержится в TOC (Table of Content). Некоторые элементы TOC можно отметить ранее созданными условными тегами.

Как видно из скриншота, красным тегом были отмечены листы, необходимые только для документов в ГОСТ-стиле (при сборке документа корпоративного стиля «красные» элементы будут исключены). Синим цветом были отмечены листы для корпоративного стиля документов (при сборке документа в ГОСТ-стиле «синие» элементы будут исключены). Бесцветными остались те элементы, которые должны включаться в обе версии документации.

С помощью отметки условным тегом из документа можно исключать не только листы, но и отдельные элементы или теги внутри топиков. Таким способом для ГОСТ-стиля было исключено автособираемое мини-содержание (mini-toc proxy) в начале каждого раздела, а также команда форсированного перехода на новый лист (Page Break).

Теперь рассмотрим некоторые стилистические требования заказчика:

• отсутствие отдельных интро-листов в начале каждого раздела;
• шрифт основного текста: Times New Roman, размером 12 пунктов;
• красные строки для абзацев основного текста;
• все заголовки должны быть пронумерованы;
• ссылки на заголовки должны быть в формате «см. [N раздел.N пункта]» (к примеру, см. 1.4);
• нумерация картинок в формате: «Рис. [N раздела.N рисунка]» (к примеру, Рис. 1.1);
• ссылки на рисунки из текста должны быть в формате «см. рис. N.N»;
• нумерация таблиц в формате «Табл. [N раздела.N таблицы]» (к примеру, Табл. 1.1);
• ссылки на таблицы из текста должны быть в формате «см. табл. N.N»;
• при переходе таблицы на другую страницу к её названию должна прибавляться приставка «(продолжение)».

Для стилистической адаптации потребуется новый Medium. С помощью Medium можно переопределять стандартные настройки тегов в CSS-таблице стилей. На скриншоте ниже показано, как был переопределен стиль для заголовков разделов (тег h1). Как видно, для Medium для ГОСТ был переопределен стиль шрифта (font-family), цвет шрифта (color), горизонтальное выравнивание блока (text-align), удалено подчеркивание (text-decoration) и задан формат нумерации (mc-auto-number-format).

Для переопределения стиля перекрестных ссылок используются встроенные команды Flare. К примеру, команда {page} вставляет номер целевой страницы в ссылку, а команда {paranumonly} «вырезает» элемент авто-нумерации из какого-либо тега, что дает возможность делать ссылки типа: «см. рис. 4.2» или «см. табл. 5.12».

Аналогичным образом, с помощью Medium, переопределяются стили для всех остальных тегов:

• шрифт основного текста (тег p);
• стили заголовков (теги h1, h2, h3 и т.д.);
• стиль рисунков (тег img).

Некоторые теги можно просто исключать из сборки, отметив их условным тегом (Condition Tag). Подобным образом можно поступить с тегом Caption, который определяет стиль и содержание блока с названием таблицы. Так как блок с названием требуется таблицам исключительно для ГОСТ-стиля, то можно отметить его красным условным тегом (атрибут mc-conditions), тем самым исключив его попадание в документы корпоративного стиля. Прочие атрибуты блока Caption (text-align, caption-side, mc-caption-continuation, mc-caption-repeat, mc-auto-number-format) определяют положение и выравнивание блока подписи, его поведение при переносе таблицы на следующую страницу, а также правило автонумерации таблиц.

После того, как проект адаптирован, и структурно, и стилистически, остается создать и настроить новую цель (Target):

• указать созданный ранее макет (Page Layout) для ГОСТ-стиля;
• пометить на включение (Include) красный тег GOST и на исключение (Exclude) синий тег Norm, чтобы в сборку документа попадали только нужные элементы;

• на вкладке Variables переопределить (если требуется) значения переменных, которые были «вшиты» в макеты (Page Layout);
• в настройке глоссария поставить переключатель «Do not convert terms», чтобы термины из глоссария не превращались в сноски (по требованию заказчика для глоссария был отведен отдельный лист);
• указать ранее созданный Medium.

Теперь можно запустить сборку нового Target и полюбоваться результатом – документ облачён в каноничную ГОСТовую обертку, как и хотел госзаказчик.

Для окончательной автоматизации (чтобы оба типа документов строились одним кликом) можно создать Batch – задание на пакетную сборку нескольких Target. Отметим флажками обе Target. Если требуется, то на вкладке Schedule можно настроить автоматическую сборку комплекта по расписанию.

Тэги: Flare, MadCap, опыт, стандарты, форматирование, шаблоны