HTTPS SSH

<docbook>ЕСПД</docbook>

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

Лицензия

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Репозиторий расположен на BitBucket,
склонируйте с помощью Git:
git clone git@bitbucket.org:Lab50/espd-docbook5.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/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

Стилевые файлы располагаются по адресу http://lab50.net/xsl/espd/. Например, вы
можете включить в ваше описание стиля:

<xsl:import href="http://lab50.net/xsl/espd/espd.xsl"/>

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

Примеры

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

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

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

  • 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".