oXygen XML Editor

В редакторе три режима работы:

При навигации по тексту смотри на "хлебные крошки":

Рисунок 4. Хлебные крошки

Корректность вставки какого-либо тэга зависит от того, где ты находишься. Визуальное представление места нахождения может быть обманчивым.

Если с верхней панелью всё более-менее ясно, особенно с панелью редактирования в режиме Author, то по нескольким боковым панелям пройдусь.

Слева ниже находится панель Outline – это древовидная структура документа на основе вложенности тэгов. Удобно смотреть, где ты находишься, скрывать/раскрывать блоки, перетаскивать блоки с места на место. По кнопке можно видоизменять это дерево.

Справа выше важные панели Elements и Attributes. Это тэги и их атрибуты. Например, если надо выделить текст моноширинным шрифтом, то выделите его, в панели Elements найдите тэг code и совершите по нему двойной клик. Потом при нахождении курсора внутри тэга code можно на панели Attributes дать ему какой-либо атрибут, например id. Для этого ячейке Value строки id надо совершить двойной клик и ввести значение.

Есть атрибуты с предустановленным списком возможных значений. Находясь внутри тэга можно познакомиться с моделью этого элемента (какие тэги могут находится внутри и какие атрибуты с какими значениями возможны) на панели Model. Также на этой панели есть справка по тэгу.

Справа ниже панель, ради которой весь этот сыр-бор с DocBook и затевался – это панель Transformation Scenarious для настройки и публикации конечного документа.

Если вы выведите документ в PDF согласно предустановленному сценарию "DocBook PDF", вероятно, будете несколько разочарованы, потому что вам не всё форматирование понравится. Программа предоставляет инструмент настройки выходных форматов по кнопке , которая активируется при выделении сценария в разделе копий Project. Открывается окно:

Рисунок 5. Настройка сценария трансформации

Здесь всё можно оставить как есть и воспользоваться только кнопкой [Parameters]. При нажатии на эту кнопку откроется список XSL параметров, которые можно изменить:

Рисунок 6. Параметры трансформации

Здесь надо выделить нужный параметр и нажать кнопку [Edit] для его изменения. Я, например, под себя произвел такие изменения:

Еще была проблема с наклонным шрифтом – он не отображался, т.к. ему был назначен какой-то непонятный шрифт. В параметрах я сделал Calibri первым шрифтом в нескольких местах, и, какое место сработало, затрудняюсь сказать.

В настройках программы не все параметры доступны. Их больше в файле <ПУТЬ_К_ПАПКЕ_РЕДАКТОРА>\frameworks\docbook\xsl\fo\param.xsl. Я его также правил под себя и вносил в него даже отсутствующие и в этом файле параметры. Атрибуты надо редактировать или добавлять в контейнере xsl:attribute-set, а параметры в xsl:param. Например:

Форматирование блока Примечаний

<xsl:attribute-set name="graphical.admonition.properties">
  <xsl:attribute name="font-size">10pt</xsl:attribute> <!-- Размер шрифта -->
  <xsl:attribute name="color">#900</xsl:attribute> <!-- Цвет всего текста содержимого -->
  <xsl:attribute name="background-color">#EEE</xsl:attribute> <!-- Цвет заливки -->
  <xsl:attribute name="margin-left">3em</xsl:attribute> <!-- Сдвиг слева -->
  <xsl:attribute name="padding">0.4em</xsl:attribute> <!-- Отступы внутри блока -->
</xsl:attribute-set> 

Надеюсь, понятно, что текст в <!-- ... --> это просто комментарий к коду и воспроизводить его в файле не обязательно.

Формат шрифта верхнего колонтитула

<xsl:attribute-set name="header.content.properties">
  <xsl:attribute name="font-size">10pt</xsl:attribute>
  <xsl:attribute name="color">#555</xsl:attribute>
</xsl:attribute-set>

Форматирование ячеек таблицы

<xsl:attribute-set name="table.properties">
  <xsl:attribute name="font-size">10pt</xsl:attribute>
  <xsl:attribute name="text-align">left</xsl:attribute>
</xsl:attribute-set>

Списки

<xsl:attribute-set name="list.block.properties">
 <xsl:attribute name="margin-left">3em</xsl:attribute> <!-- Сдвиг списка от левого края -->
</xsl:attribute-set>

Заголовки документа

<xsl:attribute-set name="section.title.level2.properties">
 <xsl:attribute name="margin-left">25pt</xsl:attribute>
</xsl:attribute-set>

Здесь я сдвинул заголовок 2-го уровня на 25 пунктов от левого края. Аналогично на другие позиции сдвинул заголовки более низких уровней.

Листинги

<xsl:attribute-set name="monospace.verbatim.properties">
 <xsl:attribute name="font-size">8pt</xsl:attribute>
 <xsl:attribute name="padding">5pt</xsl:attribute>
</xsl:attribute-set>

Влияет на содержимое <programlisting>. Удалось уменьшить размер шрифта и сделать отступы от краев блока, но не удалось пока переносить длинные строки.

Ссылки

<xsl:attribute-set name="xref.properties">
 <xsl:attribute name="color">#0000FF</xsl:attribute> <!-- Пусть цвет ссылок будет синим -->
</xsl:attribute-set>

Картинки

<xsl:attribute-set name="figure.properties">
  <xsl:attribute name="text-align">center</xsl:attribute>
</xsl:attribute-set>

Сделал выравнивание всех картинок по умолчанию по центру. В самом редакторе для отдельных картинок можно это изменить с помощью атрибута align.

Названия картинок, таблиц...

<xsl:attribute-set name="formal.title.properties">
  <xsl:attribute name="color">#555</xsl:attribute>
  <xsl:attribute name="text-align">center</xsl:attribute>
</xsl:attribute-set>

Если уж картинки сделал по центру, то и подписи к ним тоже.

Если вы еще не начали править param.xsl, руководствуясь армейской мудростью "Не спеши выполнять приказ, его могут отменить", то правильно сделали. Вот способ кастомизации стилей более удобный и безопасный: создаете файл, например, param_oparin.xsl и в него пишете дерективы, недостающие в файле param.xsl, потом в файле param.xsl вверху сразу после тэга <xsl:stylesheet> вставляете строку <xsl:import href="param_oparin.xsl"/>. Теперь вы можете править только новый файл param_oparin.xsl. Замечу, что если в двух файлах встречаются одинаковые правила, то действовать будут те, что в param.xsl, т.к. они читаются парсером позже. Пытался вставить дерективу import в конец файла, но DocBook не разрешил.

4.3. Формат WebHelp

Представление документации в Интернете – насущная потребность многих компаний и разработчиков софта. И не только софта. WebHelp – очень выигрышный формат. Древовидное интерактивное содержание документа слева. В основной области страницы открывается содержание активного раздела. Есть навигация в виде кнопок [Next], [Previous], [Up], [Home]. Есть поиск по всему документу и подсветка найденного контекста на странице открывшегося раздела.

Для этого формата генерятся два индексных файла index.html (красивый дизайн) и index_frames.html (простой дизайн). При просмотре на локальном компьютере в современных браузерах есть особенность: в index.html не отрабатываются гиперссылки в силу политики безопасности, в то время как на сервере всё OK.

Еще советы по настройке сценария WebHelp:

По умолчанию в Oxygen нет трансформации в формат MS Word. Поэтому, рекомендую из готового PDF конвертировать в Word сторонними программами. Известные мне на практике приложения, умеющие PDF конвертировать в Word с удобоваримым результатом:

1. PDFgear
2. Adobe Acrobat
3. MS Word 365
4. AVS Document Converter
5. Abbyy Transformer+
6. Abbyy FineReader
7. Nitro PDF
8. Soda PDF (онлайн)

Список ранжирован по мере потери качества конвертирования. Но это не значит, что Soda самый худший. Есть и другие программы, которые в список не вошли из-за неприемлемого качества. Возможно мне что-то еще неизвестно, поэтому список не претендует на абсолютную объективность. Подразумевается, что текст в pdf – это не картинка. В противном случае рекомендуется только Abbyy FineReader, потому что лучше всех в мире умеет распознавать текст на изображениях.

Есть еще консольная утилита XMLmind XSL-FO Converter. Она очень грамотно переводит FO-формат в DOCX, RTF или ODT. FO – это промежуточный формат между XML и PDF. Oxygen не сохраняет его на диске во время трансформации. Он его формирует, из него делает PDF, а потом удаляет. Ковбойским методом можно этот момент подловить и сохранить для себя fo-формат вашего документа – он появляется на диске на несколько секунд после начала трансформации и его можно в это мгновение скопировать в другое место. Где эти места:
– в Windows 7 – это папка с xml-источником вашего документа, временный файл имеет расширение xml_xslt;
– в Windows 10 – это папка c:\Users\<имя_пользователя>\AppData\Local\Temp\OxygenXMLTemp\ и временный файл имеет расширение xslt.
Потом командой fo2docx из набора XMLmind XSL-FO Converter быстро превратить в docx-документ.
Если вы не ковбой, то можно пойти другим путем – запустите трансформацию в режиме отладки (кнопка [Debug Scenario]), интерфейс программы поменяется – вы увидите три окна, вас будет интересовать третье окно "Text", пока пустое. Нажмите кнопку-стрелочку [Run]. Через некоторое время в третьем окне "Text" появится fo-код. Кликните по нему правой кнопки мыши и сохраните на диск с любым именем. Потом применяйте к сохраненному файлу батник fo2docx.
Ну а если делать всё по уму, то можно прописать через меню Oxygen новый fo-процессор так: Options > Preferences > XML / XSLT-FO-XQuery / FO Processors > кнопка [New] > прописать путь к папке: <путь_к_xmlmind-процессору>\bin и прописать командную строку:
– в Windows 7: <путь_к_xmlmind-процессору>\bin\fo2docx.bat ${cfd}\${cfn}.xml_xslt ${cfd}\docx\${cfn}.docx
– в Windows 10: <путь_к_xmlmind-процессору>\bin\fo2docx.bat c:\Users\<имя_пользователя>\AppData\Local\Temp\OxygenXMLTemp\*.xslt ${cfd}\out\${cfn}.docx
и дать имя процессору, например, XMLmind. Потом в настройках нового сценария транформации выбрать этот новый процессор вместо Apache FOP.

Есть разные варианты отображения ссылок (например, номер страницы указывать...) - их можно варьировать с помощью атрибута xrefstyle.

При работе с таблицей сразу захотелось сделать заливку ячеек первой строки. Не нашел инструмента в Oxygen (в самом-то редакторе заливка есть, а при выводе в PDF – нет). Но нашел такой рецепт: в любое место внутри тэга <row> прописать fo-команду <?dbfo bgcolor="#EEE"?> и всё.
По умолчанию в таблице есть границы снаружи и внутри. Иногда надо сделать таблицу без них. Убрать внешние границы: атрибуту frame таблицы дать значение none. Убрать границы внутри между ячеек: в тэге colspec присвоить атрибутам colsep и rowsep значение 0.
Как сделать другие настройки таблицы и ссылок через файл param.xsl написано в выше.

Крайне полезная функция таких технологий как DocBook – это принцип единого источника. Один блок текста, например, может присутствовать в разных документах, но не в виде его неотъемлемой составной части, а в виде вставки. Таким образом, редактирование этого текста в одном месте повлечет изменения во всех документах сразу, что удобно и более безопасно.

Чтобы осуществить такую вставку надо сначала подготовить документ-донор как обычный xml файл, и задать id в нем нужной секции <section>.

Далее в документе-реципиенте поставить курсор в то место, куда будет вставляться секция, и нажать на кнопку . В открывшемся окне найти нужный файл, выделить нужную секцию и нажать [OK].

Секция будет вставлена на место курсора.

Если теперь переключиться в текстовой режим, то увидим запись типа такой:

<xi:include href="section_for_include.xml" xpointer="someblock"
         xmlns:xi="http://www.w3.org/2001/XInclude"/>

Чтобы отредактировать текст вставки надо ПКМ вызвать контекстное меню и выбрать Edit Reference. Файл откроется в новой закладке редактора. После его редактирования и сохранения изменения в документе-реципиенте отразятся автоматически.

Картинки в текст можно вставлять посредством тэгов:

Чем такой докбуковский метод вставки картинок выгодно отличается от вордовского - тем, что картинки хранятся в отдельной папке с быстрым доступ к ним для просмотра или замены. При необходимости замены не надо этим заниматься в редакторе, достаточно перезаписать файл на диске.