 | Уровень сложности: простой Боб дю Шарм, архитектор решений, Innodata Isogen
03.07.2009 С помощью инструментария DITA Open Toolkit можно конвертировать документы DITA во множество различных форматов. На первый взгляд может показаться, что для работы с ним вам необходимо хорошо знать Ant, но это не так. Большинство функций инструментария можно использовать из командной строки, вызывая консольное Java™-приложение с различными параметрами.
Введение
Архитектура для подготовки технической документации (Document Information Typing Architecture – DITA) представляет собой набор типов XML-документов для использования в процессе документирования, ориентированном на выбранную тему. DITA также включает в себя механизмы для создания специализированных версий типов документов для более точного соответствия структуре информации. Это делается путем изменения нужных DTD или XML-схем. Как это часто бывает, одним из преимуществ DITA является то, что, следуя этой архитектуре, вы получаете возможность использовать коммерческое и свободное программное обеспечение, специально разработанное для поддержки данного стандарта.
Из бесплатного ПО наиболее популярным является инструментарий DITA Open Toolkit (DITA OT) – инфраструктура на основе Java для обработки файлов DITA. C его помощью вы можете взять ваши XML-документы в формате DITA (или, еще лучше, документы, созданные по вашим собственным специализированным версиям схем DITA) и преобразовать их в форматы HTML, PDF, RTF, troff, файлов справки Eclipse и некоторые другие.
Как только я впервые установил данный инструментарий, я запустил демонстрационную сборку, следуя инструкциям в разделе “Проверка установки” (см. Ресурсы). Набор форматов, в которые можно преобразовать документы DITA, произвел на меня впечатление. Однако должен признаться, что затем я был несколько сбит с толку. Дело в том, что демонстрацией управлял скрипт Ant, в котором было более 800 строк и, более того, он включал в себя еще один Ant-скрипт, который, в свою очередь, содержал ссылки еще на дюжину файлов. Не обладая уверенными навыками работы с Ant, мне было непросто выяснить, какие именно части скриптов следует вынести в отдельный файл, чтобы просто преобразовать один из моих документов DITA в формат XHTML или PDF.
В итоге я разобрался, как заставить DITA OT сконвертировать данный документ DITA в любой из поддерживаемых форматов. Для этого даже не потребуется заглядывать внутрь скриптов Ant, достаточно лишь командной строки.
Что именно автоматизирует инструментарий DITA Open Toolkit?
Для выполнения корректного преобразования в общем случае недостаточно просто взять XSLT-процессор, например Xalan или Saxon и применить таблицу стилей DITA OT whatever.xsl к документу DITA mydoc.xml. Необходимо также установить значения некоторых переменных окружения и учесть другие связи, чтобы все компоненты DITA OT заработали правильно. Это особенно важно, в случае использования специализированных типов. Например, допустим, что элемент ingredients в вашем документе рецептов является специализацией стандартного DITA-элемента prereq, а вам нужно создать HTML-представления рецептов. В случае, если для элемента ingredients не задано никакого специального сценария обработки, DITA OT должен выполнить определенные действия, чтобы выяснить, что этот элемент надо обрабатывать так же, как prereq.
Конфигурирование подобных действий – это во многом именно то, чем занимается демонстрационный скрипт Ant. Аналогичным образом можно использовать скрипты Ant для автоматизации преобразования ваших файлов в нужные форматы с помощью DITA OT. Тем из вас, у кого нет ни навыков использования Ant, ни времени на их приобретение, будет приятно узнать, что существует другой способ автоматизация этих действий. Для этого существует файл dost.jar, включенный в DITA OT. Все, что требуется – это указать, какой файл DITA надо преобразовать, и задать требуемый выходной формат.
Использование файла dost.jar
Как и в случае многих качественных jar-файлов, если вы запустите среду исполнения Java с ключом -jar и именем файла в качестве единственного параметра, то на экран будет выведен список доступных параметров. Всего их около 30 и, несмотря на то, что по утверждению разработчиков dost.jar вам нужно минимум два параметра, я выяснил, что достаточно и одного: имени входного файла. При выполнении следующей команды в домашнем каталоге DITA OT инструментарий генерирует XHTML-версию файла currywurst.xml и по умолчанию помещает ее в поддиректорию out:
java -jar lib/dost.jar /i:C:/temp/currywurst.xml
|
Так как, судя по документации, оба параметра (/i - для указания имени файла и /transtype – для типа преобразования) являются обязательными, я бы не стал полагаться на то, что XHTML всегда по умолчанию будет выступать в качестве выходного формата.
Но самое интересное начинается при экспериментировании с другими форматами, например:
java -jar lib/dost.jar /i:C:/temp/currywurst.xml /transtype:pdf
|
При выполнении данной строки будет создан файл XSL-FO на основе исходного файла DITA. Если на вашем компьютере установлена библиотека Apache FOP и значения всех необходимых переменных заданы в соответствии с инструкцией по установке DITA Open Toolkit, то c ее помощью файл XSL-FO будет преобразован в PDF. И все это делается одной достаточно простой командой!
Я не собираюсь перечислять все, что написано в документации о каждом из доступных параметров, но я вам открою один секрет, очень важный для понимания предоставляемых возможностей. Ни одна страница документации DITA Open Toolkit сама по себе не содержит исчерпывающей информации о параметрах командной строки. Для этого вам понадобятся две страницы, а именно: "Processing from the Java command line", на которой перечислены все поддерживаемые параметры, например, /i или /transtype, и соответствующие им параметры скрипта Ant, а также "Ant processing parameters", описывающая функции параметров и их значения по умолчанию. Ссылки на данные страницы можно найти в разделе Ресурсы.
Но даже на этих страницах вы не найдете полного списка допустимых значений параметра /transtype. Для этого вам придется указать в качестве данного параметра заведомо некорректное значение, после чего dost.jar выдаст список поддерживаемых типов преобразования:
| Значение | Результат преобразования |
|---|
xhtml
| Документ HTML в соответствии со стандартом XHTML W3C. |
eclipsehelp
| Документ XHTML и другие файлы, необходимые для работы модуля справки среды разработки Eclipse. |
eclipsecontent
| Набор файлов, устанавливаемых в качестве подключаемого модуля Eclipse, чтобы тот мог динамически отобразить информацию. |
javahelp
| Файл входных данных для программы создания справки JavaHelp. |
htmlhelp
| Файл входных данных для программы создания HTML-справки в Windows. |
pdf
| Первоначально файл XSL-FO, а затем PDF, сгенерированный с помощью Apache FOP. В настоящее время вместо данного параметра следует использовать pdf2. |
pdf2
| Первоначально файл XSL-FO, а затем PDF, сгенерированный с помощью процессора Render XEP FO и подключаемого модуля Idiom. Данную возможность можно использовать только после установки модуля FO. Можно использовать и другие процессоры кроме XEP. |
troff
| Файл в формате troff, разработанном еще для ранних систем, работавших под управлением AT&T Unix®. |
docbook
| Документ XML, удовлетворяющий DTD DocBook – популярному формату технических документов. |
wordrtf
| Документ в расширенном текстовом формате (Microsoft® Rich Text Format). Этот текстовый формат был одно время популярен для конвертирования документов в формат Microsoft Word и обратно. |
Если вы создаете масштабную и сложную систему, использующую DITA Open Toolkit, то имеет смысл использовать Ant и его возможности по управлению сложными сценариями обработки. В любом случае, при использовании DITA OT Ant должен быть установлен, поэтому стоит потратить определенное время на его изучение, написав несколько скриптов на основе тех, что включены в DITA OT. Если же вы только начинаете работать с DITA OT, то dost.jar – это то, что нужно для того, чтобы опробовать все возможности инструментария. Вам остается только экспериментировать с различными параметрами командной строки, вводя различные комбинации и анализируя результат. Пробуйте и получайте удовольствие!
Ресурсы Научиться
- Оригинал статьи: “Tip: Easy command line processing with DITA Open Toolkit” (Боб дю Шарм, developerWorks, январь 2008 г.). (EN)
- Прочитайте руководство по полной установке инструментария DITA. Установите и опробуйте в работе инструментарий DITA Open Toolkit. (EN)
- Обратитесь к документации о параметрах Ant, содержащей информацию о допустимых значениях, значениях по умолчанию, вариантах использования, а также полный список параметров в алфавитном порядке. (EN)
- Прочитайте документацию по использованию DITA Open Toolkit из командной строки. В ней содержится руководство по запуску инструментария из командной строки вместо использования Ant, а также приводится список поддерживаемых параметров. (EN)
- Прочитайте статью “Введение в архитектуру для подготовки технической документации Darwin” (developerWorks, Дон Дэй (Don Day), Майкл Пристли (Michael Priestley), Дэвид Шелл (David Schell), сентябрь 2005 г.), в которой описывается архитектура DITA и способы ее применения для подготовки технической документации, например, online-справки или Web-портала для поддержки определенного продукта. (EN)
- Ознакомьтесь со списком часто задаваемых вопросов об архитектуре DITA (developerWorks Дон Дэй (Don Day), Майкл Пристли (Michael Priestley), Гретчен Харгис (Gretchen Hargis); сентябрь 2005 г.). В нем вы найдете ответы, советы и подходы к использованию DITA для создания документации. (EN)
- Прочитайте руководство “Apache Ant 101: Моментальная сборка приложений на Java” (developerWorks, Мэтт Чэпман (Matt Chapman), декабрь 2003 г.), в котором сначала рассказывается о создании скрипта для сборки простого проекта на Java, а затем описываются более полезные функции, такие как операции с файловой системой и сопоставление с образцом (pattern matching). Кроме того, вы узнаете, как создавать собственные Java-классы для добавления новых функций Ant. (EN)
-
Технические мероприятия и Web-трансляции developerWorks: В этих разделах можно получить самую актуальную информацию о современных технологиях. (EN)
- Обратитесь к магазину технической литературы, в котором представлены книги на данную и другие темы. (EN)
Получить продукты и технологии
- Посетите домашнюю страницу DITA на сервере sourceforge. Конвертируйте содержимое DITA-документов (карты и темы) в нужные форматы с помощью данной реализации спецификации DITA, разработанной техническим комитетом OASIS. Инструментарий написан на Java и поддерживает DITA DTD и XML-схемы. Его можно использовать под операционными системами Windows, Linux/UNIX и Mac OS. (EN)
- Скачайте ознакомительные версии программного обеспечения IBM: используйте в вашем следующем проекте ознакомительные версии ПО, которые можно скачать прямо с сайта IBM developerWorks. (EN)
Обсудить
Об авторе | 
| | Боб дю Шарм (Bob DuCharme), занимающий на данный момент должность архитектора решений в компании Innodata Isogen, считался экспертом по XML еще в те времена, когда для обозначения этого языка использовалась четырехбуквенная аббревиатура. Он написал четыре книги и около 100 статей (как напечатанных, так и доступных online) на тему информационных технологий, ни разу не использовав слово “функциональность”. Более подробную информацию о Бобе можно найти на странице http://www.snee.com/bob, а его Web-блог размещен по адресу www.snee.com/bobdc.blog. |
Выскажите мнение об этой странице
| |
