Первая страница

oXygen XML Editor

обзор программы
Онлайн: РИСОВАЛКИ | ИГРЫ | РЕЛАКС программы

Анатолий Опарин / август, 2018

Содержание:
Введение
1. Моя версия
2. С чего начать
3. Интерфейс
3.1. Режимы
3.2. Панели
4. Публикация
4.1. Настройка трансформации в программе
4.2. Настройка трансформации в param.xsl
4.3. А как же Word?
5. Тренировочный раздел
5.1. Таблицы и ссылки
5.2. Вставка данных из другого документа
5.3. Изображения

Введение

oXygen XML Editor является одним из лучших XML-редакторов, предоставляющий полный набор средств разработки XML для публикации выходных документов в форматы PDF, HTML, EPUB. Редактор подхватывает пространства имен, прописанные в метаданных документа, и, согласно им, максимально облегчает пользователю работу с текстом (в том числе в визуальном режиме) - автоматически формирует список доступных элементов и список атрибутов к ним для быстрой вставки, реализует автодополнение кода, проверяет корректность кода, строит иерархическое дерево документа, позволяет схлопывать и раскрывать участки кода. Редактор имеет встроенные сценарии преобразований XSL→FO→PDF и XSL→HTML, включая XSLT, которые предназначены для обработки содержимого файлов, созданных по технологии DocBook или DITA, с предоставлением возможности кастомизировать стили, применяемые к тэгам форматирования и структурирования.
В чем наиболее важные преимущества XML редакторов на основе технологии подобных DoocBook, перед MS Word:

  • Принцип единого источника. Документ в Oxygen можно собирать из "кирпичиков" - из разных текстов, хранящихся в других файлах. В результирующем файле будут ссылки для вставки определенного куска текста из определенного файла. Если отредактировать этот "кирпичик", то изменения вступят в силу во всех файлах, в которых есть ссылка на "кирпичик". Это более быстрое и более безопасное редактирование. Еще пример уместности такого подхода: большой документ пишется разными писателями. Каждому писатели поручается писать свой раздел. Итоговый документ собирается в отдельном файле путем проставления ссылок на файлы разделов. Писатели не мешают друг другу, работая с разными частями одного документа.
  • Профилирование. Блоки данных можно помечать специальными атрибутами, которые отвечают за публикацию документа в той или иной интерпретации. Пример уместности такого подхода: руководство пользователя интернет-сервиса. Доступ к сервису осуществляется на основе ролей пользователя. Разным ролям доступны разные функции. Технический писатель может разбить описание функционала на разделы и каждому разделу дать атрибут роли. При необходимости опубликовать в конечный формат руководство определенной роли он только в одном месте меняет атрибут роли для всего документа и при публикации подхватываются только разделы, помеченные маркером нужной роли или вообще без такого маркера.
  • Отделение оформления от содержания. Писатель работает только с содержанием и разметкой. Стили форматирования элементов разметки прописаны в других файлах и после настройки не меняются. Это дает возможность сосредоточиться на смысле текста, а не его оформлении. Это страхует от сюрпризов WYSIWYG редактора, когда "куда-то не туда нажал и всё съехало". А, например, с нумерацией заголовков в Ворде, вообще, полный спотыкач. В настройках же Oxygen-DocBook автоматическая нумерация заголовков переключается только в одном параметре.
Конечно, я не призываю истинных "блондинок" пользоваться Oxygen вместо "лапочки Ворда" (это было бы жестоко), но для технических писателей и для вебмастеров, которые пишут для сайта какие-то мануалы и инструкции, это правильный выбор.

1. Моя версия

Моя версия редактора 15.2, в то время, когда самой последней версией на момент написание этого текста является 20.0. Зато моя версия портабельная и бесплатная. В конце статьи есть ссылка на скачивание.

По умолчанию в программу не встроены русские словари для проверки орфографии. Словари можно скачать по этой ссылке. С этой страницы скачиваем, например, ru_RU.zip, распаковываем и в папку c:\Users\<USER_NAME>\AppData\Roaming\com.oxygenxml\spell\ копируем из архива два файла ru_RU.aff и ru_RU.dic. В корне самой программы в папке dicts также есть эти словари, но я не пробовал сначала копировать туда. Скорее всего из этой папки они попадают в пользовательскую папку при первом запуске.

С данной сборкой я поработал пару дней и именно в ней написал, а также опубликовал в PDF и в этот HTML статью, которую вы собираетесь прочесть.

2. С чего начать

Нажать стандартную кнопку создания нового документа. Выбрать, например, "DocBook 4 > Article" (хотя в этом окне выбора фреймворка вы увидите завидное их разнообразие). В текстовом режиме можно определить, что второй строкой прописан путь к файлу docbookx.dtd - этот путь можно изменить на <ПУТЬ_К_ПАПКЕ_РЕДАКТОРА>\frameworks\docbook\4.3\dtd\docbookx.dtd или другому dtd. Структура документа типа Article состоит из элементов (тэгов) <section>. Их можно вкладывать друг в друга, создавая древовидную структуру. Тэг для параграфа: <para>.

Примечание:

Справка по тэгам DocBook см. по этой ссылке.
Полное руководство по DocBook см. здесь.

Разницу между первым путем к docbookx.dtd и вторым путем не обнаружил невооруженным взглядом. Но сразу столкнулся с тем, что подписи к картинкам начинаются со слова "Figure" и содержание называется "Table of Contents". Локализация этого решается так - тэгу <article> прописать атрибут lang="ru" так <article lang="ru"> и такие служебные названия станут на русском языке. В тэге <article> должно находиться всё содержание документа. Разделы - это или <section>, или <sec1>, <sec2>... Т.е. уровень вложенности можно задать неявно и явно. Еще один популярный контейнер для содержимого документа - <book>. В обработке <article> и <book> при трансформации есть разница. Например, в <book> в отличие от <article>, раздел первого уровня <chapter> будет называться "Глава" и начинаться с новой страницы...

3. Интерфейс

3.1. Режимы

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

  • Text. Обычный текст. При знании xml-тэгов вполне удобно. Набор открывающего тэга или его редактирование влечет появление или изменение закрывающего тэга. Есть схлоп/расхлоп блоков xml-разметки... А вот насильственное дробление длинной строки на короткие строки не понравилось, хотя у меня найдутся оппоненты. Как выкрутился:
    1. Options > Preferences > Editor >Format > cнять флаг "Hard Line Wrap" (не будет насильных разрывов строк);
    2. Options > Preferences > Editor >Text > отметить флаг "Line Wrap" (чтобы длинный строки переносились для вида).

    Рисунок 1. Режим "Text"

    Режим
  • Grid. Иерархия блоков. При навыках может быть удобным инструментом для быстрого поиска нужного участка.

    Рисунок 2. Режим "Grid"

    Режим
  • Author. WYSIWYG редактор. Если поднатореть со вставкой нужных тэгов, то это станет основным режимом работы. Конечно, не совсем "то, что видишь, то и получишь", но близко к этому.

    Рисунок 3. Режим "Author"

    Режим

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

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

Хлебные крошки

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

3.2. Панели

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

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

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

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

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

Примечание:

Если какой-то панели вы не нашли в интерфейсе или ее случайно закрыли, то ее можно вывести через меню:
Window > Show View.

4. Публикация

В терминологии Oxygen это называется трансформация, потому что разметка тэгами xml-трансформируется в PDF, HTML, EPUB - конечный формат документов. Если при создании документа выбрана нотация DocBook 4, то в окне этой панели будет список возможных форматов вывода DocBook 4. Если отметить флажок напротив нужных трансформаций и нажать кнопку , то в папку out (по умолчанию, но путь к выходному файлу можно изменить) будет сохранен открытый документ в выбранных форматах. Представленные программой сценарии трансформации править нельзя, но можно сделать копию трансформации кнопкой и её уже настроить под себя.

Очень понравился результат трансформации в формат DocBook WebHelp - получаются стильные и удобные документы для просмотра в Интернете, созданные по примеру CHM-файлов (Windows Help) - с древовидным навигационным сайдбаром слева. Для этого формата генерятся два индексных файла index.html (фреймы на основе js) и index_frames.html (фреймы на основе html-тэгов). Если у вас вдруг при запуске первого не будут отображаться страницы разделов, то нажмите вверху справа кнопку перехода в index_frames.html или просто пользуйтесь им как стартовым файлом.

Также обратите внимание на сценарий трансформации DocBook WebHelp - Modile. Результат адаптирован для мобильных устройств с небольшим экраном.

4.1. Настройка трансформации в программе

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

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

Настройка сценария трансформации

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

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

Параметры трансформации

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

  • section.autolabel = 1 (Включил нумерацию заголовков)

  • toc.section.depth (Глубина отображения заголовков в содержании)

  • page.margin.* (Отступ страницы от краев листа)

  • body.margin.* (Отступ тела страницы от краев страницы)

  • body.font.* (Основной шрифт)

  • header.column.widths = 1 15 1 (Относительные размеры трех частей верхнего колонтитула. Если оставить как было 1 1 1, то тексту колонтитула будет отведена слишком узкая ширина и он будет разделен на 2-3 строки.)

  • profile.* - профилирование (Например, поставил profile.userlevel='admin'. В тексте одному абзацу дал атрибут userlevel='admin', а второму userlevel='man'. После публикации - первый абзац виден, а второй - нет.)

  • monospace.font.family = Courier New (Шрифт листинга <programlisting>, иначе в листинге не отображается русский)

  • formal.title.placement (Расположение подписей для картинок, таблиц... - под или перед ними)

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

4.2. Настройка трансформации в param.xsl

В настройках программы не все параметры доступны. Их больше в файле <ПУТЬ_К_ПАПКЕ_РЕДАКТОРА>\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.cell.padding">
  <xsl:attribute name="padding">4pt</xsl:attribute>
  <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. А как же Word?

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

  1. Adobe Acrobat

  2. MS Word 365

  3. AVS Document Converter

  4. Abbyy Transformer+

  5. Abbyy FineReader

  6. Nitro PDF

  7. Soda PDF (онлайн)

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

Есть еще консольная утилита XMLmind XSL-FO Converter. Она очень грамотно переводит FO-формат в PDF. FO - это промежуточный формат между XML и PDF. Видимо, Oxygen не хранит его на диске, потому что на выходе сразу получается PDF. А вот если бы хранил (или я знал, где он хранится), то XMLmind XSL-FO Converter был бы самым лучшим вариантом.

5. Тренировочный раздел

Здесь протестирую элементы, которые не встретились выше, но которые пригодятся в работе техническому писателю (таблицы и некоторые типы ссылок), а также потренируемся с картинками.

5.1. Таблицы и ссылки

Таблица 1. Ссылки работают так

Тип ссылкиПояснение
xrefЕсли присвоить разделу <section> (ни в коем случае не <title>) id, а потом прописать <xref linkend="paramxsl"/> в качестве ссылки на этот раздел, то в PDF вместо этого кода будет Раздел 4.2, «Настройка трансформации в param.xsl».
linkЕсли прописать <link linkend="paramxsl">ссылка</link> , то ссылка будет именно со слова ссылка.
ulinkЭто для внешних ссылок. URL в PDF состоит из анкора и самого URL обрамляемого квадратными скобками [ и ].

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

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

5.2. Вставка данных из другого документа

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

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

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

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

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

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

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

5.3. Изображения

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

  • inlinegraphic - для вставки иконок и др. маленьких изображений в строку. На панели инструментов в режиме Author для этого выделена кнопка . Тут никаких сложностей нет.

  • figure - для вставки блочного элемента с картинкой (для скриншотов и больших иллюстраций) с автоматической нумерацией названий картинок. Без привычки трудно разобраться сначала как правильно вставлять. Итак, в визуальном редакторе:

    1. На панели Elements совершить двойной клик по тэгу <figure>.

    2. Будет создан контейнер <figure> и в нем элемент <title>, внутрь которого курсор и установится. Ввести заголовок картинки.

    3. В конце заголовка с помощью стрелочки выйти из <title> и оказаться в <figure> (следите за этим в хлебных крошках или в Elements).

    4. Найти элемент <mediaobject> и совершить двойной клик по нему.

    5. Количество возможных элементов для вставки в этот тэг уменьшится в окошке Elements. В нем кликнуть двойным приемом по тэгу <imageobject>.

    6. Вставится и этот тэг, и внутрь него вставится <imagedata>.

    7. Находясь в <imagedata> надо ему прописать атрибут fileref, для чего вызвать контекстное меню ПКМ на нем и выбрать Edit Attributes.

    8. В поле Name открывшегося окна выбрать fileref и для поля Value найти на диске нужную картинку.

    Теперь, если посмотреть код в режиме Text, то можно увидеть такую конструкцию:

    <figure>
      <title>Параметры трансформации</title>
      <mediaobject>
        <imageobject>
          <imagedata fileref="img/ox-07.png"/>
        </imageobject>
      </mediaobject>
    </figure>

    По мне, так легче забить этот код в какой-нибудь шаблон, например, с помощью Punto Switcher, и по горячим клавишам генерировать его в документе в текстовом режиме.

    Если еще говорить о картинках в <figure>, то стоит упомянуть такие атрибуты тэга <imagedata>, как align (выравнивание по горизонтали) и scale (масштаб в процентах). Часто встречается потребность сослаться на картинку из другого участка документа, тогда предварительно <figure> надо задать атрибут id, чтобы было, на что ссылаться.

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

6. Скачать

В этом архиве (пароль для разархивации: newart.ru) сам редактор, xml-верстка статьи, pdf-результат статьи, мой файл дополнительных стилей. Разархивируйте zip и скопируйте папку редактора в любое место. В файле <ПУТЬ_К_ПАПКЕ_РЕДАКТОРА>\#serial.txt вы найдете инструкцию по регистрации. Для регистрации и последующей работы программы требуется Java на вашем компьютере. К программе прилагается пример проекта данной статьи, сделанной в Oxygen:

about_my_Oxygen.xml - источник текста статьи
section_for_include.xml - кусок текста, который в статью вставлен инклюдом для тренировки
about_my_Oxygen.pdf - результирующий PDF
param_oparin.xsl - мной созданный файл дополнительного форматирования для импорта в родной файл <ПАПКА_ПРОГРАММЫ>\frameworks\docbook\xsl\fo\param.xsl с помощью директивы <xsl:import href="param_oparin.xsl"/>.

Анатолий Опарин (при перепечатке указывать авторство)

Новости

Объявление Творческой личности
домой | живопись | графика | компьютерная графика | поделки | юные художники | темы | комментарии | перлы
конкурсы | игры | релакс | рисовалки | учиться рисовать | детские карты Москвы | детские стихи | статьи | видео | поиск | обратная связь