КомпанияУслугиОбучениеСервисы

Arbortext: система разработки, генерации и публикации технической документации

Версия для печати

Arbortext: система разработки, генерации и публикации технической документации

Олег Волков, компания «Продуктивные Технологические Системы», специалист направления ИЛП, 2009

Семейство продуктов

Arbortext — семейство продуктов американской компании-гиганта PTC (Parametric Technology Corp.), предназначенное для создания технической документации. В своей основе Arbortext использует принцип единого источника, в основе которого лежит формат XML. Статья будет посвящена в основном Arbortext Editor with Styler, который является основным инструментом технического писателя. Рассмотрим краткий обзор части продуктов линейки Arbortext и их назначение, так как в дальнейшем эти продукты могут упоминаться.

  • Arbortext Editor — мощный XML редактор, интегрируемый с другими продуктами компании PTC (в числе которых база данных CSDB for S1000D, система PLM Windchill и т. д.). Поддерживает многочисленные форматы выходных публикаций, такие как Web, PDF, HTML Help, Digital Media Publisher.

  • Arbortext Styler — надстройка, интегрированная в Arbortext Editor, позволяющая с помощью визуального интерфейса легко создавать и редактировать стили, применяемые при публикации XML источника в различные форматы. Очень часто Arbortext Editor выбирается именно в комплектации Arbortext Editor with Styler.

  • Arbortext ISO Draw — система для создания технических иллюстраций. Arbortext IsoDraw автоматизирует процесс создания высококачественных 2D и 3D технических иллюстраций и анимаций прямо из трехмерных моделей. Иллюстрации автоматически обновляются при изменении исходных моделей САПР.

  • Arbortext Publishing Engine — сетевой сервер для публикации. Позволяет подбирать и публиковать материал в соответствии с выбранными требованиями содержания и формата. Содержит машину для публикации в формат IETP.

  • Arbortext CSDB for S1000D (Arbortext ASD 1000D) является полностью настроенным решением «под ключ», реализующим техническую документацию в соответствии со спецификациями ASD 1000D и ASD 2000M.

Почему именно Arbortext?

Высокая степень интегрированности продуктов Arbortext c другими продуктами PTC позволяет осуществлять разработку документации не просто в XML редакторе, но в специальной среде разработки. Эта среда дает возможность не только создавать XML, но и хранить документацию, создавать интерактивные иллюстрации, организовывать параллельную работу по созданию документации нескольким участникам процесса, в то время, как большинство редакторов — замкнутые решения для локального пользователя, нацеленные больше на какие-то свои изыски, но не на законченное решение.

Функциональность самого редактора, которая будет подробно рассмотрена далее, отвечает всем современным требованиям для организации профессиональной работы по разработке документации — с одной стороны. С другой стороны, Arbortext Editor создан для того, чтобы скорее начать работу и получить результат, не нуждаясь в специфических знаниях о XML, XSL-FO, тонкостях инсталляции стандартов, типов документов и т. д.

Практически всегда документация разрабатывается не с чистого листа. Многие понимают, что при переходе на использование единого источника данных в формате XML потребуется не только организовать разработку документации, но при этом использовать имеющиеся наработки. Arbortext содержит конфигурируемый модуль для импорта данных из Microsoft Word и Adobe FrameMaker в формат XML.

Функциональность Arbortext Editor

Приятные моменты рабочего процесса

Начав работу и решив создать новый документ, мы сразу же видим предустановленные ВЕВ: DITA, DocBook/XML, SMA (service manual application — специализация на основе DITA) и другие. Нет необходимости устанавливать или настраивать DITA или DocBook. Добавление нового типа документа происходит указанием нового DTD (на рисунке также видны собственные типы документов, которые были созданы и добавлены — elantra, glava, trg_ditabase).

Предустановленные типы документов

Выбор пункта Sample позволяет нам открыть предустановленный пример документа того или иного типа для ознакомления. На рисунке ниже мы видим интерфейс Arbortext Editor с открытым образцом документа в формате DITA Topic. Придирчивый пользователь может настраивать цвета, панели, отображение элементов на свой вкус.

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

Интерфейс. Предустановленный образец выбранного типа документа

Окно атрибутов может быть быстро вызвано горячей клавишей в зависимости от положения курсора в окне редактирования или дереве документа

Экран по умолчанию разбит на 2 фрейма: слева дерево документа, справа — область редактирования. Разбиение экрана на 2 фрейма можно убирать, располагать по-другому, а можно заменять, выбрав, например, менеджер ресурсов, как вы видите на рисунке ниже. Менеджер ресурсов может отображать имеющуюся графику, структуру ссылок и связей с другими XML документами, заимствованные части контента.

Менеджер ресурсов (изображений, контентных ссылок, элементов структуры, на которые разбиваются документы)

Документы могут быть представлены как сборки из файловых сущностей, сборки из наборов ссылок. Это позволяет организовать одновременную работу над документом нескольких пользователей. На примере ниже инструкция по обкатке автомобиля, которая параллельно формировалась из двух частей — файловых сущностей.

Функция Compare позволяет отслеживать изменения, осуществляя сравнение текущего документа с последней сохранённой версией, с документом из другого файла или из другого открытого окна Arbortext Editor. Мы можем отследить, было ли в новой версии произведено редактирование, удаление или же добавление части текста. Как видно на рисунке, из списка был удалён один пункт, но мы видим, в каком месте он находился.

Функция сравнения отслеживает изменения в документа

Arbortext Editor может включать функцию импорта документов различных форматов в формат XML.

Импорт документов в формат

Для импорта используется специальный шаблон STD. Можно использовать готовые шаблоны, а можно воспользоваться встроенным редактором. На примере ниже мы видим некоторый проект импорта, в котором начата работа по созданию своего шаблона для конвертации файлов Microsoft Word в XML.

В левой колонке мы видим элементы исходного документа Word, а в колонке справа — элементы DTD. Для создания своего шаблона импорта мы сопоставляем их

В Editor удобно создавать профилирование документов (рисунок ниже). Заполняя атрибуты элементов (например, разделов) и привязывая их к некоторому профилю (например, Новичок) мы можем затем просматривать или публиковать информацию, предназначенную для специализированной аудитории. Например, на рисунке ниже мы собираемся применить профиль, нацеленный на публикацию только для неопытных пользователей.

Применение профиля для публикации: только для начинающих пользователей

При этом не стоит волноваться за нумерацию параграфов и заголовков. При публикации для подобного профиля вся нумерация будет пересчитана в рамках нового документа и автоматически сформировано новое оглавление.

Профили для каждого нашего документа хранятся в файле и размещаются в каталоге с DTD. Мы можем создавать файл профилей в среде Editor, опять же, не прибегая непосредственно к кодированию. На рисунке ниже видно, как мы сформировали простое дерево, рассчитанное на 3 варианта публикации: полный документ, разделы только для конструктора, разделы только для технолога.

Создание файла профиля для возможности публикации частей документа, адресованных конкретной целевой аудитории

Помимо файла профилей PCF мы можем аналогичным образом создать файлы навесок и настроек, применительно к данному типу документа:

  • Файл переименований .alias — если мы хотим, чтобы теги XML в интерфейсе Arbortext Editor назывались по-другому. Например <para> может отображаться как Параграф, <li> как Следующий пункт. Полезная возможность, когда мы хотим предложить работу в Editor человеку, который ранее не был знаком с HTML/XML, но привык к работе в Microsoft Word.

  • Файл настроек .DCF (document type configuration), в котором мы можем в рамках определённого типа документа настраивать функциональность панели инструментов, пользовательские словари, автоматическую вставку одних тегов вокруг других, запрещать редактирование/скрывать определённые атрибуты или теги и многое, многое другое.

  • Файл применяемых стилей публикации, создаваемый в Arbortext Styler.

Arbortext Styler

Styler — эффективная опция Arbortext Editor, позволяющая создавать в визуальном редакторе собственные стили публикации во все форматы, применяемые к XML источнику. Styler проглатывает уже созданные стили XSL-FO, либо формирует свои стили в формате fosi, xsl-fo или родном формате с расширением .style. Возможно также получить стиль в формате XSL.

Окно Arbortext Styler

Создание стиля в визуальном редакторе

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

Стиль охватывает все элементы DTD и даёт возможность стилизовать не только каждый элемент DTD в отдельности, но и формировать:

  • Вставку генерируемого текста. Некоторый текст до и после некоторых элементов выделяется цветом (по умолчанию — синим) и недоступен для редактирования. Это значит, что он генерируется автоматически. С помощью гентекста, например, формируется содержание, подписи под рисунками, автоматическая нумерация глав и списков, расстановка символа копирайта и т. д.

Гентекст: элементы, выделенные синим цветом, сгенерированны автоматически и не редактируются напрямую

Формирование содержания:

Настройки формата и стиля для генерируемого содержания в Styler

  • Наследования — если элементу принудительно не заданы некоторые параметры (отступ, шрифт и т.д), он наследует их от родителя

  • Контекстные условия — мы можем стилизовать отдельно параграф, отдельно параграф в главе, отдельно параграф в параграфе и т.д.

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

  • Возможность в рамках одного стиля задавать некоторые нюансы, которые будут применимы только для PDF, только для Web, только для Help и т. д.

Помимо перечисленного, Styler содержит свою панель для публикации и предпросмотра документов, поддержку языка XPath

Интерактив

Возможность публикации и просмотра непосредственно в Arbortext Editor трехмерных изображений в формате ISO и CGM порадует пользователей, нацеленных на публикацию в HTML, PDF 3D или IETP.

Публикация 3D модели. При открытии HTML срабатывает плагин на Internet Explorer для просмотра векторной и 3D графики — ISOview

Создав иллюстрацию в Arbortext IsoDraw, мы можем помещать в тексте двусторонние ссылки, связывающие текст и элементы чертежа. Это могут быть интерактивные «горячие точки», выноски, просто текстовые ссылки. Рисунок ниже, иллюстрирует функцию ViewPorts. В опубликованной в формат HTML спецификации каждая позиция является ссылкой, при нажатии на которую нас переносит на векторную иллюстрацию и происходит фокусировка и крупное масштабирование детали, с которой связана эта позиция спецификации.

Фокусировка и увеличение объектов векторной иллюстрации при нажатии на текстовую ссылку

Сгенерированный документ в формате HTML Help

Среда разработки

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

  • Arbortext CSDB for S1000D. ASD 1000D (S 1000D) является средой «под ключ» разработки, создания, управления и эксплуатации технических публикаций применительно к гражданской и военной Авиационной и Оборонной промышленности. Формат статьи не позволяет широко раскрыть особенности продукта, более подробную информацию можно найти по ссылке http://pts-russia.com/products/arbortext_asd.htm

  • Система обеспечения жизненного цикла изделий Windchill. Являясь веб-ориентированной PLM системой, где клиентом является обычный Internet Explorer, Windchill формирует среду для хранения данных и разработки изделия, обеспечивает полноценный workflow. Windchill особенно незаменима, когда участники проекта сильно удалены друг от друга, но имеют доступ к локальной или глобальной сети. Пользователь может сформировать правила, по которым загружаемые XML документы будут разбиваться на несколько файлов, превращаясь в сборку для формирования параллельной работы удалённых пользователей и формирования книг на основе повторного использования частей документации.

Кто это использует?

В России продукты Arbortext широко применяются на предприятиях авиационной промышленности. Клиентами компании PTS (Продуктивные Технологические Системы) уже стали АО НПО «Иркут», ОАО «Туполев», НПО «Сатурн», ОКБ им. А.С. Яковлева, ТАНТК им. Бериева, ГП Киевский Авиационный Завод «Авиант», ЦСКБ «Прогресс».

В следующей версии

Наиболее интересные, на мой взгляд, дополнения в Arbortext Editor 5.4:

  • Arbortext Editor 5.4 будет поддерживать русский интерфейс.

  • Расширенные возможности копирования/вставки. Теперь при копировании контента, например, из Adobe FrameMaker или Word структура скопированного текста будет сохраняться. Таблица будет вставляться как таблица, форматирование жирных, курсивных элементов, списков, заголовков и тому подобного будут вставляться в XML документ с добавлением соответствующих тегов разметки.

  • Появится функция, очерчивающая область контента внутри тега. Особенно наглядно для элементов типа inline, располагающихся на нескольких строках.

  • Расширенные возможности отслеживания изменений.

  • Многое другое, о чём нет возможности рассказать в настоящей статье.

Версия Arbortext 5.4 должна выйти весной 2009 года.

Где можно приобрести продукты

Компания PTS (Продуктивные Технологические системы: http://pts-russia.com) является дистрибьютером Parametric Technology Corporation в России. Это значит, что покупая программные продукты и техническую поддержку, вы не останетесь один на один с неизвестным софтом.

© «Философт», 2008–2017

+7 (499) 500-44-77

mail@philosoft.ru

SpyLOG