Формальные структуры текстовых документов (стр. 3 )

lineage

Часть имени, описывающая отношение к предкам (напр., «мл.»; в случае царствующих особ – номер при имени; и т. п.). Содержание элемента lineage такое же, как и у других элементов имён (символьно-смешанное), ожидания обработки – такие же:

lineage ::=
(#PCDATA|link|olink|ulink|emphasis|trademark|replaceable|remark|
subscript|superscript|inlinegraphic|inlinemediaobject|indexterm)*

honorific

Титул (звание и пр.). По составу и ожиданиям обработки совпадает с другими элемента­ми имени (символьно-смешанное содержимое).

authorblurb, personblurb

Названия этих элементов происходят от blurb – краткая издательская реклама или ан­но­тация (часто помещаемая на обложку книги). Оба этих элемента содержат необязатель­ное заглавие, за которым следуют обычные аб­зацы:

authorblurb ::= (title?, (formalpara|para|simpara)+)
personblurb ::= (title?, (formalpara|para|simpara)+)

Ожи­дания обработки

Блок или подавление визуализации.

affiliation

Принадлежность персоны к организации.

affiliation ::= (shortaffil?,jobtitle*,orgname?,orgdiv*,address*)

Необязательное краткое описание (shortaffil – символьно-смешанное содержимое), за которым следуют должность (jobtitle), название ор­ганизации (orgname), название подразделения (orgdiv) и адрес (address). Любой из по­с­ледних четырех элементов может отсутствовать, но хотя бы один из них должен быть. Дол­жностей, подразделений и адресов может быть несколько, но организация, если она указана, – только одна.

Содержимое jobtitle и orgdiv символьно-смешанное, элементы orgname и address обладают особыми атрибутами, а address – ещё и иной структурой.

Ожи­дания обработки

Зависят от контекста: может быть потоковым элементом, блоком или не визуализи­роваться.

orgname

Название организации имеет символьно-смешанное содержимое:

orgname ::=
(#PCDATA|link|olink|ulink|emphasis|trademark|replaceable|remark|
subscript|superscript|inlinegraphic|inlinemediaobject|indexterm)*

Для организаций вне элемента affiliation лучше использовать элемент corpname, по составу совпадающий с affiliation, но не имеющий специальных атрибутов.

Атрибуты

Имя атрибута	Тип значения атрибута	Описание
otherclass	CDATA	Строка, описывающая тип организации, если значение атрибута class равно "other"
class	(consortium| corporation| informal| nonprofit| other)	Тип организации. Умолчание отсутствует.

address

Адрес может содержать множество составляющих (в произвольном количестве и произ­вольном порядке:

address ::=
(#PCDATA|personname|honorific|firstname|surname|lineage|othername|
affiliation|authorblurb|contrib|street|pob|postcode|city|state|
country|phone|fax|email|otheraddr)*

Каждый элемент адреса имеет символьно-смешанное содержимое.

Атрибуты

Имя атрибута	Тип значения атрибута	Описание
linenumbering	(numbered| unnumbered)	linenumbering = "numbered" требует нуме­ро­вать строки адреса, linenumbering = "unnumbered" отменяет нумерацию. Поло­же­ние номеров строк определяется обраба­ты­вающим приложением.
language	CDATA	Назначение не описано
xml:space	(preserve)	Сохранение пробельного материала
continuation	(continues| restarts)	Если continuation = "continues", то нуме­рация строк адреса (если linenumbering = "numbered") продолжается от номера последней строки предыдущего элемента address, иначе начинается с 1.
format	(linespecific)	Умолчание: "linespecific". Означает, что пробельный материал должен быть сохранён (видимо, рудимент SGML)
startinglinenumber	CDATA	Начальный номер строки адреса (при нумерации)

Лекция 4.  Обработка документов DocBook с помощью стилевых файлов XSLT

Для изучения существующих способов обработки документов DocBook с помощью сти­ле­вых файлов XSLT существуют два источника: свободно распространяемый набор стилевых файлов DocBook XSL (в последней стабильной версии 1.69.1 от 11 ав­гус­та 2005 г. – 1934 файла общим объемом более 14 Мб) и книга Б. Сейтона 2. Любая книга отстаёт от разви­тия программного обеспечения; книга Сейтона – не исключение (последние изменения в неё внесены в феврале 2005 г.).

Стандартный набор стилевых файлов

Стандартный набор стилевых файлов DocBook (DocBook XSL) предоставляет разнообраз­ные возможнос­ти визуализации документов DocBook: HTML, XHTML (оба варианта – как один большой файл или как набор нескольких меньших файлов), HTML Help и JavaHelp, Formatting Objects для непосредственного вывода на печать и получения PDF. Этот набор файлов мож­но скачать с http://docbook. .

Архив, содержащий DocBook XSL, содержит следующие каталоги (эту же структуру сле­ду­ет сохранить при его распаковке):

w  common

Общие модули всех стилевых файлов (включая настройку на язык)

w  extensions

Программы, необходимые для расширения возможностей DocBook XSL для конкретных XSLT-процессоров

w  fo

Модули для получения вывода в формате XSL-FO

w  html

Модули для получения вывода в формате HTML

w  images

Значки и другие изображения, используемые при порождении вывода

w  lib

Компоненты, не зависящие от DTD

Этот архив содержит также и другие каталоги, содержащие модули, предназначенные для получения других видов вывода и использования DocBook XSL с некоторыми распро­страненными приложениями (например, Eclipse).

Документация DocBook XSL поставляется отдельным архивом, который содержит два ка­талога:

w  doc

Документация в HTML-формате (фактически, часть книги 1, несколько устаревшая)

w  docsrc

Документы DocBook, из которых получена документация.

Кроме поддержки распространенных форматов вывода, существует отдельный набор сти­левых файлов, обеспечивающий поддержку веб-сайтов, получаемых из документов DocBook, – DocBook Website.

Комплект DocBook XSL может быть распакован в любой каталог файловой системы, одна­ко для его эффективного использования может понадобиться настройка XML-каталога. Для применения DocBook XSL необходим XSLT-процессор (например, встроенный в Windows MSXML), а для получения Formatting Objects и/или PDF – и другие програм­м­ные средства (XSL-FO-процессор, Adobe Acrobat или иные средства генерации PDF).

Использование параметров DocBook XSL

DocBook XSL имеет огромное количество параметров, которые позволяют в значительной мере изменять поведение DocBook XSL при генерации вывода (в основном эти параметры относятся к порождению вывода, предназначенного для печати – FO или PDF). Для мно­гих XSLT-процес­соров эти параметры можно задавать в командной строке, но если таких параметров мно­го, то следует применить т. н. «слой настройки» (“customization layer”) – собрать пара­метры в один или несколько файлов («обёртки»). Например, задать стилевой файл для порождаемого HTML и задать особое выделение для предупреждений в тексте можно так:

<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www. w3.org/1999/XSL/Transform"
version="1.0">
<xsl:import href="/usr/share/xsl/docbook/html/docbook. xsl"/>
<xsl:param name="html. stylesheet" select="'corpstyle. css'"/>
<xsl:param name="admon. graphics" select="1"/> </xsl:stylesheet>

Этот файл следует присоединить к документу DocBook или использовать в командной строке XSLT-процессора.

Значения всех строковых параметров должны заключаться в апострофы (обратите внима­ние на то, что имя стилевого файла CSS записано как 'corpstyle. css').

При использовании слоя настройки DocBook XSL следует обращать внимание на исполь­зо­вание путей: XSLT-процессор не всегда считает, что рабочий каталог совпадает с тем, в котором находится обрабатываемый документ, так что рекомендуется использовать URL с абсолютными путями, например:

В документе DocBook:

<?xml-stylesheet type="text/xsl"
href="C:\DISCIPLINES\510 Document Structures\my. xsl"?>

В стилевом файле my. xsl:

<xsl:param name="html. stylesheet" select="'file:///C:/DISCIPLINES/510%20Document%20Structures/my. css'"/>

Настройка порождения HTML

Порождение HTML-документа из документа DocBook может быть параметризовано для:

w  Разбиения одного документа DocBook на несколько HTML-файлов

w  Обработки части документа DocBook (например, одной книги из комплекта)

w  Перекодирования документа в другую кодировку с указанием кодировки

w  Подключения CSS к выходному документу

w  Изменения способов нумерации глав и/или секций

w  Указания графических изображений для предупреждений, навигации (в случае порождения нескольких HTML-документов) и выносок

w  Форматирования дат и времени (не работает с MSXML, – XML-процессором, по умолчанию используемом в Windows)

Подключение CSS к выходному HTML-документу

Подключение CSS к выходному HTML-документу проиллюстрировано выше.

Для использования CSS необходимо знать, какие элементы HTML из каких элементов DocBook порождаются. Проще всего выяснить это, выполнив XSL-преобразование, по­сколь­ку от версии к версии DocBook XSL это соответствие может изменяться. Вот неко­то­рые соответствия для версий DocBook 4.2 и DocBook XSL 1.69.1:

bookinfoàtitle ⇒ h1 class="title" bookinfoàsubtitle ⇒ h2 class="subtitle" bookinfoàauthor ⇒ div class="author"
bookinfoàauthoràfirstname ⇒ h3 class="author" bookinfoàauthoràlastname ⇒ h3 class="author"
part ⇒ div class="part" partàtitle ⇒ <div class="titlepage">
<div>
<h1 class="title">Part Title</h1>
</div>
</div>
chapter ⇒ div class="chapter" chapteràtitle ⇒ <div class="titlepage">
<div> <h2 class="title">Chapter Title</h2>
</div>
</div>
section1 ⇒ div class="section1" section1àtitle ⇒ <div class="titlepage">
<div> <h2 class="title">Section1 Title</h2>
</div>
</div>
para ⇒ p
emphasis ⇒ em
phrase ⇒ span

Обратите внимание на то, что и заголовки глав и заголовки секций первого уровня в HTML преобразуются в заголовки второго уровня, и, если вы хотите, чтобы они вы­гля­де­ли по-разному, нужно тщательно проектировать CSS:

div. chapter div. titlepage h2.title { font-size: 16pt; }
div. section1 div. titlepage h2.title { font-size: 14pt; }

Подавление локальных оглавлений средствами CSS

Без дополнительной настройки DocBook XSL порождает оглавления для каждого струк­турного раздела документа: глав и секций любого уровня. Зачастую это нежелательно. Прос­тейший способ подавить визуализацию такого оглавления (не порождение, а имен­но только визуализацию) – использовать CSS, поскольку оглавления помещаются в от­дель­ные идентифицируемые блоки:

div class="toc"

помещённые внутрь блока структурного раздела. Например, чтобы подавить визуали­за­цию оглавления от уровня частей книги и глубже, достаточно использовать следующий стиль:

div. part div. toc { display: none; }

Для выборочного отображения оглавлений придётся потрудиться. Например, для подав­ления визуализации оглавлений на уровне частей, но вывода оглавлений на уровне глав придется использовать

div. part div. toc { display: none; }
div. chapter div. toc { display: block; }

Пользовательские классы

Для четырёх элементов DocBook возможно автоматическое преобразование атрибута role в класс CSS. Это элементы para (абзац), emphasis (выделение), phrase (фраза) и entry (ячейка таблицы). Для включения такого преобразования в стилевой файл – обёр­т­ку XSLT – следует добавить строки вида (пример приведён для абзаца):

<xsl:param name="para.propagate. style" select="1"/>

а в стилевой файл CSS – требуемый стиль:

p.special { background-color: rgb(128,255,64); }

Тогда абзацы (элементы документа DocBook) с атрибутом role="special" при выводе приобретут зеленоватый цвет.

Поскольку элемент phrase не имеет в DocBook строго определенной семантики, то ис­поль­зование этого элемента с различными классифицирующими ролями позволяет раз­работать т. н. «микроформат» – собственную систему классов CSS, передающую семантику предметной области документа.

DocBook XSL может передавать в HTML и значения атрибута id, однако возможности та­кой передачи ограничены небольшим набором элементов уровня главы и выше.

Управление нумерацией

Для подавления нумерации главоподобных элементов или секций в XSLT-обёртку сле­ду­ет включать строки вида:

<xsl:param name="chapter. autolabel" select="0"/>

Вместо chapter может стоять имя любого элемента, для которого необходимо подавить нумерацию (appendix, section и т. п.). Можно подавить нумерацию на определённой глубине вложенности элементов:

<xsl:param name="section. autolabel. max. depth" select="2"/>

Тонкая настройка DocBook XSL

DocBook XSL, как уже говорилось, имеет большое количество настроек. Здесь мы рассмот­рим только две из них: настройку языка и настройку оглавлений.

Указание языка

DocBook XSL содержит служебные текстовые строки для порождения элементов заголов­ков (например, «Глава») на 45 языках. Для применения необходимого языка соответству­ю­щий элемент должен иметь необходимое значение атрибута lang:

<book lang="ru"> . . .</book>

Но вместо этого можно использовать параметр DocBook XSL, управляющий лока­лизаци­ей порождаемого текста:

<xsl:param name="l10n. gentext. language" select="'ru'"/>

Замечание

Программный продукт Authentic компании Altova поставляется с устаревшим набо­ром файлов DocBook XSL, не поддерживающим локализацию.

Управление оглавлениями

Для управления оглавлениями DocBook XSL использует параметр generate. toc. В отли­чие от большинства других параметров DocBook XSL, этот параметр является непустым элементом, например (значения по умолчанию):

<xsl:param name="generate. toc">
appendix toc, title
article/appendix nop
article toc, title
book toc, title, figure, table, example, equation
chapter toc, title
part toc, title
preface toc, title
qandadiv toc
qandaset toc
reference toc, title
sect1 toc
sect2 toc
sect3 toc
sect4 toc
sect5 toc
section toc
set toc, title
</xsl:param>

Значение этого параметра – пары, разделённые пробельным материалом (ведущие про­белы не учитываются). Первый элемент пары – имя элемента, второй – список подпара­мет­ров, указы­ва­ю­щий, какое именно оглавление будет сформировано для этого элемента (частный случай – никакого). В списке подпараметров возможно использование следую­щих значений:

w  toc

Следует генерировать оглавление (из заглавий вложенных элементов)

w  nop

Не генерировать оглавление

w  title

Включать заглавие оглавления, например, «Содержание»

w  figure, table, example, equation ...

Перечень элементов, для которых следует генерировать оглавление (указатель)

В качестве разделителя в списке подпараметров используется запятая, пробелы не допус­каются.

Управление глубиной оглавления

Глубиной оглавления можно управлять при помощи параметра toc. section. depth:

<xsl:param name="toc. section. depth" select="0"/>

выводит в оглавление книги только список глав и полностью подавляет оглавления в гла­вах; положительные значения toc. section. depth определяют уровень вложенности сек­ций, до которого заглавия секций включаются в оглавление. По умолчанию параметр toc. section. depth имеет значение 2., т. е. в оглавления выводятся заглавия двух верхних уровней секций.

Рассмотренный параметр управляет «абсолютной» глубиной используемых в оглавлени­ях заголовков. DocBook XSL позволяет использовать и другой параметр, toc. max. depth, управляющий «относительной» глубиной:

<xsl:param name="toc. max. depth" select="2"/>

заставит XSLT-преобразование вывести во все оглавления заглавия (глав/секций) не более чем на два уровня вглубь.

Выборочное исключение заглавия элемента из оглавления

Для выборочного исключения заглавия элемента из оглавления используется атрибут role. Если, например, значение этого атрибута, равное 'NotInToc', должно означать, что заголовок соответствующей секции не должен попадать в оглавление, в XSLT-обёртку следует добавить правило:

<xsl:template match="section[@role = 'NotInToc']" mode="toc" />

которое фактически отключит порождение строки оглавления для секции с указанным значением атрибута role.

Оглавления секций

В приведённом на предыдущей странице параметре generate. toc по умолчанию сек­ции всех уровней имеют оглавления. Однако рассмотрение реально сгенерированного вы­вода показывает, что секции оглавлений не имеют. Такое поведение связано с наличием ещё одного настроечного параметра – generate. section. toc. level, определяющего глу­бину вложенности секции, для которой будет создано оглавление. Оглавление также может отсутствовать из-за того, что включение необходимых заглавий подавлено пара­мет­ром toc. section. depth.

Параметры generate. section. toc. level, toc. section. depth и toc. max. depth поз­во­ляют гибко управлять видимостью заголовков в оглавлениях. Их взаимодействие проще всего представить на следующих примерах:

Таблица 1
Управление глубиной оглавлений (generate. section. toc. level / toc. section. depth) –
абсолютный уровень включаемых секций

generate. section. toc. level	toc. section. depth	Оглавление секции включает:
sect1	sect2	sect3	sect4
1	2	sect2	Пусто	Пусто	Пусто
3	sect2 sect3	Пусто	Пусто	Пусто
4	sect2 sect3 sect4	Пусто	Пусто	Пусто
2	2	sect2	Пусто	Пусто	Пусто
3	sect2 sect3	sect3	Пусто	Пусто
4	sect2 sect3 sect4	sect3 sect4	Пусто	Пусто
3	2	sect2	Пусто	Пусто	Пусто
3	sect2 sect3	sect3	Пусто	Пусто
4	sect2 sect3 sect4	sect3 sect4	sect4	Пусто

Таблица 1 построена в предположении, что параметр toc. max. depth имеет достаточно большое значение.

Таблица 2
Управление глубиной оглавлений (generate. section. toc. level / toc. max. depth) –
относительный уровень включаемых секций

generate. section. toc. level	toc. max. depth	Оглавление секции включает:
sect1	sect2	sect3	sect4
1	1	sect2	Пусто	Пусто	Пусто
2	sect2 sect3	Пусто	Пусто	Пусто
3	sect2 sect3  sect4	Пусто	Пусто	Пусто
2	1	sect2	sect3	Пусто	Пусто
2	sect2 sect3	sect3 sect4	Пусто	Пусто
3	sect2 sect3 sect4	sect3 sect4 sect5	Пусто	Пусто
3	1	sect2	sect3	sect4	Пусто
2	sect2 sect3	sect3 sect4	sect4 sect5	Пусто
3	sect2 sect3 sect4	sect3 sect4  sect5	sect4 sect5  [sect6]	Пусто

Таблица 2 построена в предположении, что параметр toc. section. depth имеет доста­точно большое значение.