ЕСПД

Данный проект предназначен для оформления документации по стандарту ЕСПД в формате DocBook 5.

Лицензия

Все материалы распространяются на условиях стандартной общественной лицензии GNU (GPL) версии 3.

Полный текст лицензии находится в файле COPYING.

Что это такое?

Проект ЕСПД создан для форматирования документов в формате DocBook по стандарту ЕСПД. Помимо стилей форматирования содержит шаблоны наиболее распространенных документов.

В репозитории лежат XSL стили DocBook на основе стандартных стилей XSL-FO для создания PDF документов. Помимо требований стандарта ЕСПД, предлагаемый набор стилей старается следовать общим правилам русского оформления документов.

На текущий момент в проекте существует три основных стиля: строгие ЕСПД и ЕСКД и «современный». Современный стиль может использоваться для создания документации на русском языке, но не требующей строго соблюдения стандартов. Так же имеется библиотека стилей ЕСКД. В ней содержатся стили оформления таблиц и рисунков, списков перечислений и листа регистрации изменений.

При сборке документации в стиле ЕСКД, на каждом листе появляется рамка и основная надпись (ГОСТ 2.104-2006). Основная надпись привязана к первому разделу документа — к аннотации (<preface>). Рамка замещает собой нижние колонтитулы листа (footer).

Какие требования

Для правильной верстки необходимы:

• Apache FOP версии 2.0+, рекомендуется актуальная версия из репозитория.

• DocBook XSL версии не менее 1.78.

• csvtool, если вы планируете использовать Makefile из нашего проекта.

• Для работы с русским языком крайне рекомендуется использовать FOP в связке с Saxon вместо штатного для многих дистрибутивов Xalan.

Как это использовать?

Стилевые файлы соответствуют стандарту XSL и модифицируют стандартный набор XSL-FO. Генерировать документы можно распространенными XSLT и FO процессорами. У нас используются xsltproc и Apache FO.

Репозиторий расположен на GitHub, склонируйте с помощью Git:

git clone https://github.com/laboratory50/espd-docbook.git

Подключить стиль можно с помощью директивы xml-stylesheet непосредственно в вашем документе:

<?xml version="1.0" encoding="utf-8"?>
<?xml-model … ?>
<!-- для стиля ЕСПД -->
<?xml-stylesheet type="text/xsl" href="~/espd-docbook5/espd/espd.xsl"?>
<!-- для стиля ЕСПД с профилями -->
<?xml-stylesheet type="text/xsl" href="~/espd-docbook5/espd/espd-profile.xsl"?>
<!-- для стиля ЕСКД -->
<?xml-stylesheet type="text/xsl" href="~/espd-docbook5/espd/eskd.xsl"?>
<!-- или для современного стиля -->
<?xml-stylesheet type="text/xsl" href="~/espd-docbook5/espd/modern.xsl"?>
<book>
 …
</book>

или непосредственно в командной строке процессора

xsltproc ~/espd-docbook5/espd/espd.xsl mybook.xml

или Apache FOP:

fop -catalog -c ~/espd-docbook5/fop.xml -xml mybook.xml -xsl ~/espd-docbook5/espd/espd.xsl \
-param espd.decimal 'Децимальный номер' -pdf mybook.pdf

mybook.xml — ваш документ.

Пример включения файлов стиля ЕСПД в собственный можно посмотреть в файле sample.xsl.

Примеры

Шаблоны документов ЕСПД расположены в каталоге шаблоны. Там же есть файл Makefile, с помощью которого можно собрать комплект документации. Это хороший тест на правильность настройки вашей среды.

Стилевые параметры

Стиль ЕСПД содержит ряд параметров, с помощью которых можно влиять на выходное оформление.

• espd.decimal Децимальный номер документа.

• espd.lri Создание листа регистрации изменений (включено).

• espd.text-indent Абзацный отступ. Помимо абзацев используется для выравнивания многих элементов (перечислений, названий разделов). Рекомендуется абсолютное значение.

• espd.heading.font.family Шрифт колонтитулов. Стандартное значение — title.font.family.

• espd.verbatim.font.size Размер шрифта для блоков машинного текста (programlisting и т.п.). Стандартное значение 11pt. Должно быть в абсолютных единицах.

• espd.heading.separation Форматирование заголовков с отступом между номером и названием. Если включен такой режим, используются параметры набора heading.properties. Значение 0/1. Только для современного стиля.

• espd.verbatim.color.bg Цвет фона абзацев машинного текста.

Лист утверждения и титульный лист

Листы утверждения для стилей ЕСПД (ГОСТ 19.104-78) и ЕСКД (ГОСТ 2.105-95). Начиная с версии 2.1 лист утверждения — обложка (front.cover). Для отключения листа утверждения нужно создать front.cover пустым в вашем стилевом файле:

<xsl:template name="front.cover"/>

Для всех листов утверждения оформление устанавливается набором стилевых параметров lu.style, а для титульных страниц — набором стилевых параметров espd.titlepage.style. Состав информации на титульных листах задаётся через шаблоны графических элементов (штампа и/или рамки) и наполнения для стилей ЕСПД и ЕСКД. Содержание титульной страницы современного стиля задаётся произвольно.

Подсчёт количества страниц в документу осуществляется с помощью команды <?lastpage?>. Его вручную следует добавить в конец (в последний раздел) документа.

Набор из автора, нормоконтролёра, утверждающего и пр. определяется элементами в <authorgroup>. В шапку утверждающим выносится <editor> (утверждающий), также должен присутствовать элемент <author>. Любые иные уважаемые персоны (в любом количестве) должны определяться элементами <othercredit> (согласующие). В шаблонах <editor> отображается в правой части, <othercredit> — в левой.

Каждый обозначенный элемент должен содержать:

1. <personname>, включая <firstname>, <surname>, <othername>,
2. <affiliation>, содержащий <jobtitle> (должность) и <orgname> (организация).

Пример:

<authorgroup>
    <author>
        <personname>
            <firstname>Василий</firstname>
            <surname>Шлыков</surname>
            <othername>Александрович</othername>
        </personname>
        <affiliation>
            <jobtitle>разработчик</jobtitle>
            <orgname>ООО «Работа»</orgname>
        </affiliation>
    </author>
    <editor>
        <personname>
            <firstname>Иоанн</firstname>
            <surname>Грозный</surname>
            <othername>Васильевич</othername>
        </personname>
        <affiliation>
            <jobtitle>Царь</jobtitle>
            <orgname>Всея Руси</orgname>
        </affiliation>
    </editor>
    <othercredit>
        <personname>
            <firstname>Лев</firstname>
            <surname>Мышкин</surname>
            <othername>Николаевич</othername>
        </personname>
        <affiliation>
            <jobtitle>князь</jobtitle>
            <orgname>ООО «Княжество»</orgname>
        </affiliation>
    </othercredit>
</authorgroup>

Лист утверждения не входит в общее количество листов документа.

Для того, чтобы внизу титульной страницы печатался год, необходимо добавить элемент <pubdate>, например:

<pubdate><?dbtimestamp format="Y"?></pubdate>

Аннотации и списки аннотаций

Аннотация (<preface>) располагается сразу после титульного листа. Чтобы аннотация располагалась перед содержанием (для всех стилей), необходимо отключить автоматическое расположение содержания с помощью параметров

<xsl:param name="generate.toc">book title</xsl:param>
<xsl:param name="process.empty.source.toc" select="1"/>

Элемент <toc/> должен быть добавлен в документ вручную после раздела <preface>.

Значки аннотаций рекомендуем форматировать с помощью шрифта ZapfDingbats:

<xsl:param name="callout.unicode">1</xsl:param>
<xsl:param name="callout.graphics">0</xsl:param>

Заголовки глав и разделов

В современном стиле добавлен альтернативный вариант оформления заголовков для глав и разделов (chapter, section, sectN). При установленном параметре espd.heading.separation форматирование осуществляется следующим образом:

  1     Глава А
  1.1   Раздел Б
  Текст начиная с абзацного отступа. А
дальше как обычно.

Размер отступов определяется набором heading.properties:

<xsl:attribute-set name="heading.properties">
  <xsl:attribute name="start-indent">
    <xsl:value-of select="$espd.text-indent"/>
  </xsl:attribute>
  <xsl:attribute name="provisional-distance-between-starts">22mm</xsl:attribute>
  <xsl:attribute name="provisional-label-separation">5mm</xsl:attribute>
</xsl:attribute-set>

Если параметр espd.heading.separation не установлен, используется стандартная схема форматирования.

Оформление таблиц

С помощью параметра <?dbfo row-height="размер" ?> можно выставить необходимую высоту строки в таблице.

Для стиля ЕСПД:

• сквозная нумерации,
• название таблиц выравнивантся по левому краю,
• слово Таблица разреженное,
• после номера таблицы тире,
• в таблицах, имеющих продолжение на следующей странице, добавляются слова "Продолжение" и "Окончание" (в зависимости от необходимости),
• заголовок таблицы центрируется по ширине и высоте ячейки,
• заголовок таблицы отделён двойной чертой.

Для стиля ЕСКД:

• сквозная нумерации,
• название таблиц выравнивантся по левому краю,
• после номера таблицы точка,
• заголовок таблицы центрируется по ширине и высоте ячейки.

Для современного стиля:

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

Лист регистрации изменений

Лист регистрации изменений создаёстся в соответствии с ГОСТами ЕСПД (ГОСТ 19.604-78) и ЕСКД (ГОСТ 2.503-90). Для формирования листа регистрации необходимо установить параметр espd.lri:

<xsl:param name="espd.lri">1</xsl:param>

ЛРИ не имеет номера страницы и в общее количество страниц в документе не входит.

Изменения в стандартных элементах XSL DocBook

computeroutput

• Набор атрибутов computeroutput.properties.
• Инструкция обработки <?db-font-size размер ?>.

programlisting

• Инструкция обработки <?db-font-size размер ?>.

orderedlist

• Использование русских букв. Для корректной работы нужен XSLT-транслятор Saxon + Xerces.
• Появилась возможность выбрать символ в нумерации: «)» или «.». По умолчанию используется «)». Чтобы появилась точка, необходимо в <orderedlist> указать role="dot".