Интеграция технологии DocLine с системой разработки документации Adobe FrameMaker




Скачать 147.4 Kb.
НазваниеИнтеграция технологии DocLine с системой разработки документации Adobe FrameMaker
Дата публикации18.03.2013
Размер147.4 Kb.
ТипКурсовая
odtdocs.ru > Спорт > Курсовая
Санкт-Петербургский Государственный Университет

Математико-механический факультет
Кафедра системного программирования

Интеграция технологии DocLine с системой разработки документации Adobe FrameMaker

Курсовая работа студента 361 группы
Соколова Николая Евгеньевича

Научный руководитель К.Ю.Романовский

Санкт-Петербург

2009

Оглавление


Оглавление 2

1.Введение 2

2.Постановка задачи 3

3.Контекст 4

4.Реализация структуры DRL-документов 6

5.Результаты 7

6.Проблемы 8

7.Заключение 9

8.Список литературы 9

1Введение


В настоящее время в области программного обеспечения каждый более-менее крупный продукт имеет свою техническую документацию. Если он существует в единственной версии, то практически никаких проблем нет — существует достаточное количество программ для написания технической документации, но если уже существует несколько версий продукта, то встает вопрос о структурировании и переиспользовании технической документации. Зачем это нужно? Прежде всего ради экономии времени и денег на создание и перевод технической документации. Кроме того при переиспользовании старой документации снижается вероятность появления новых ошибок.

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

Для решения вышеописанной проблемы был разработан метод DocLine. Кроме решения данной задачи он ещё обладает возможностью подходить не только для создания документации для линии программых продуктов но и для похожих документов для схожих продуктов не входящих в одну линию. Это достигается при помощи того, что DocLine обеспечивает плановое адаптивное повторное использование при разработке и сопровождении технической документации. Планирование повторного использования означает планирование структуры многократно используемых фрагментов документации. Адаптивность повторного использования означает, что общие активы могут быть сконфигурированы независимо для включения в каждый контекст использования, то есть будут незначительно различаться в этих контекстах.

Метод DocLine состоит из языка, модели процесса разработки документации и пакета программных средств. Далее будут рассмотрены каждая из этих составляющих.

Язык DRL является базовой составляющей технологии DocLine и именно в нем заложены обозначенные выше особенности этого метода: планирование и адаптивность.

Планирование обеспечивается тем, что документ представляется в виде так называемого информационного продукта, который в ходе разработки документа должен быть сформулирован в виде финального информационного продукта. И уже на его основе автоматически создается документ, который будет входить в состав технической документации. Каждый информационный продукт состоит из составных блоков, называемых информационными элементами, которые в свою очередь также могут включать информационные элементы. Информационные элементы могут быть объединены операциями OR (выбор между информационными элементами, но без взаимоисключения) и XOR (выбор с взаимоисключением) . Планирование обеспечивается при помощи визуального языка DRL/GR.

Адаптивность в языке DRL реализована при помощи механизма, позволяющего конфигурировать информационные элементы в заранее указанных местах — точках расширения. В этих точках можно производить такие изменения как удаление информационного элемента, вставка подходящего информационного элемента или изменение нужного информационного элемента. Всё это создается при помощи языка DRL/PR.

Теперь рассмотрим модель процесса разработки технической документации. Разработка начинается с первого элемента линии. Когда возникает необходимость разработать документацию новых продуктов семейства, технический писатель анализирует схожие черты и различия продуктов семейства, выявляет возможности повторного использования, создает общие активы на основе документации первого продукта. Затем создается документация на основе общих активов. Это так называемый легковесный (сверху вниз) способ разработки технической документации, который более распространен в области разработки технической документации линий программных продуктов.

Для разработки документа DocLine используются следующие программные средства: графический редактор GLR/GR(для планирования повторного использования), XML редактор текстов документации (написанных на GLR/PR), использующийся для настройки, рефакторинга DRL-текстов и для автоматизации выделения и настройки переиспользуемых частей текста, генератор целевых документов (используемый для получения готовых документов в виде широко используемых форматов, таких как pdf или HTML) и компонента, поддерживающая циклическую разработку в DRL/GR и DRL/PR.

DocLine является XML-технологией, и она может быть понятна для программиста, но совсем не обязательно для обычного разработчика технической документации. Следовательно необходимо создание для него средств разработки. В 2007/2008м учебном году в рамках студенческого проекта был разработан плагин для среда программирования Eclipse, включающий в себя среду визуального моделирования для определения структуры документации и собственно самого редактора. Но удобного редактора, относящегося к части DRL/PR до сих пор нет. Обычные XML-редакторы не предоставляют нужный функционал и удобство использования. Было сделано предположение, что не имеет смысла писать с нуля специализированный XML-редактор, а надо просто интегрировать нужный нам набор инструментов в какой-либо уже имеющийся продукт для разработки структурированной документации. Это решает как проблему отсутствия наглядности документа, так и проблему реализации ограничений , накладываемых на XML-документ, являющийся DocLine-документом. Таким продуктом был выбран Adobe FrameMaker.
^

2Постановка задачи


Общая задача участников студенческого проекта - разработка плагина к Adobe Framemaker, позволяющего производить базовые операции над документами языка DRL:

  • создание новых документов

  • редактирование уже существующих

  • импортирование в Adobe Framemaker документов, представленных в виде XML-файлов

  • экспортирование документов Adobe Framemaker в DRL-документы

  • Публикация

  • Проверка целостности технической документации.



Задачей данной курсовой работы были:

  1. Обучение новым технологиям

    1. Получить навыки работы с Adobe FrameMaker 8.0.

    2. Получить навыки работы с FrameMaker 8.0 Developer Kit (8.0 FDK)

  2. Разрботка представления структуры DRL-документов в Adobe FrameMaker

    1. Перенос иерархии для DRL-документов, представленных в виде XML в Adobe FrameMaker.

    2. Разработка разделения документации на базовые структурные типы Adobe FrameMaker - структурные книги и структурные документы.

  3. Создание плагина.

    1. Реализация простого открытия документов Adobe FrameMaker, соответствующих DRL и открытия документов с проверкой соответствия содержимого докуметации , преставленной в виде книги Adobe FrameMaker, и содержимого папки с документацией.

    2. Разработка и реализация механизмов импортирования/экспортирования документов языка DRL в/из Adobe FrameMaker.

  4. Интеграция с другими участниками проекта с целью создания единого рабочего плагина.

3Контекст


Adobe FrameMaker:

  • Документ Adobe FrameMaker - файл, содержащий документацию или какую-то её часть. Adobe FrameMaker имеет два типа документов и, соответственно, два режима работы с документацией Стандартный и Структурный. Основным различием между ними является то, что в структурном режиме для работы с документацией добавлется некоторое колличество доплнительных панелей, таких как структурное представление документа (все документы структурны, но другое дело, что это может быть только один уровень структуры, и в стандартном режиме структура скрыта - пользователь работает исключительно с текстом) и различные панели для работы с ним - список элементов, которые можно добавить в конкретное место структуры, правила для отображения и др.

  • Книга Adobe FrameMaker - упорядоченный набор ссылок на документы Adobe FrameMaker. Как и документы может являться структурной и неструктурной.

Плагин Docline:

  • Открытие

    Открытие ранее созданного документа Adobe FrameMaker может быть дву типов: простое открытие и открытие с проверкой соответствия. Простое открытие - это обычное открытие документа с помощью Adobe FrameMaker. При открытии с проверкой соответствия для каждой компоненты книги Adobe FrameMaker проверяется наличие соответствующего ей файла и наоборот - для каждого документа Adobe FrameMaker, являющегося документом Docline, проверяется его наличи в книге. В случае невыполнения первого - из книги удаляется "лишняя" компонента, а в случае невыполнения второго - добавляется.

  • Импортирование

    Импортирование GLR-документа в FrameMaker – процесс открытия документа с помощью FrameMaker-а с использованием специального механизма, встроенного в FrameMaker и преобразование его во внутреннее представление FrameMaker-а. На вход функции импортирования передается GRL-файл, представленный в виде .drl файла и по-сути являющийся XML-файлом. На выхоже получается книга FrameMaker-а, главы которой соответствуют частям документации. Полученная книга должна целиком соответсвовать документации и в ней не должно появиться никакой «лишней» и дублирущей другие части информации. Для XML-файлов в FrameMaker-е уже есть встроенная функция, которая (если отдельно задано описание такого типа XML-файлов) импортирует файл и представляет его в виде книги с каким-то колличеством глав, которые соответствуют документам FrameMaker-а. Но этой функции недостаточно по ряду причин. Первая причина — это то, что GRL-документ может быть разбит на несколько файлов, просто лежащих в одной папке и никак не связанных с друг другом. Нам требуется объединить эти все документы в одну книгу внутри FrameMaker-а. Вторая причина — это необходимость сохранения обратной связи с исходными drl-файлами, чтобы при последующем экспортировании можно было получить (если, конечно, ввнутри FrameMaker-а не изменялась структура книги, соответствующий GRL-документу) исходные файлы с изменённым содержанием.

  • Экспортирование

    Экспортирование GRL-документа в FrameMaker – процесс преобразоваания книги, находящейся внутри FrameMaker-а и соответствующей определённому GRL-документу в его изныачальное XML-представлние в виде drl-файла. В FrameMaker-е также есть втроенная функция экпортирования, но она также не удовлетворяет выдвигаемым для нее требованиям. Документ, в который экспортируется книга, является как и требуется XML-файлом, но по содержанию она является просто набором ссылок на документы, сответствующие главам книги внутри FrameMaker-а. Но это не удовлетворяет поставленным задачам, поскольку на выходе требуется получить XML-документы, которые можно без труда редактировать в любых XML-редакторах, в том числе и в примитивных текстовых редакторах. Критерием правильности было выбрано свойство идентичности документа, прошедшего импорт и экспорт, и исходного документа.

  • Проверка целостности

    Проверка целостности - проверка документации на наличие ошибок, связанных с её структурой. Базовая часть проверки возможна при помощи встроенной проверки по представлению структуры DocLine внутри Adobe FrameMaker. Данная процедура аналогична валидации XML-документа по соответсвующему ему DTD (Document Type Definition - файл с описанием элеметов XML-документа и их структуры) и, соответсвенно, проверяет только структурную составляющую документа. Кроме неё надо проверять ещё целостность всех ссылок документа. Поскольку элемент, на который ссылаются, идентифицируется исключительно при помощи аттрибутов, стандартная XML-валидация (или соответствующая её валидация внутри Adobe Framemaker), не позволяет узнать существует ли в пределах видимости (книга для Adobe Framemaker и текущий каталог для XML) нужный элемент.

  • Публикация

    Публикация GRL-документа - это преобразование его в один из нередактируемых форматов представления документации, таких как pdf-документ или html-страница. Внутри Adobe FrameMaker есть встроенная функция преобразования книг и документов в наиболее популярные форматы. Но она не учитывает особенность технологии DocLine - требуется не просто преобразование книги или документа, а "сборка" его по всем внутренним ссылкам в конечную документацию. Для этого надо предварительно проверить целостность этого документа, а уже только после этого использовать функцию публикации, которая в свою очередь включает в себя экспортирование документа внутри Adobe FrameMaker в XML-представление и вызов реализованной ранее функции написанной на языке программирования Java.
^

4Реализация структуры DRL-документов


Каждое структурное приложение Adobe FrameMaker для корректного отбражения и работы с ним внутри Adobe FrameMaker должно удовлетворять заданному для него описанию структуры - либо оно долно являться одним из описанных заранее типов приложений, либо в него должно быть отдельно импортирвано описание его структуры - EDD(Element Data Definitios) - аналог DTD для XML-файлов.

Для работы в данном проекте, естественно, требуется структное представление документов Adobe FrameMaker и следовательно требуется реализовать правила для элементов структуры документов docline. Поскольку одной из задач является реализация функций импортирования/экспортирования, которые в базовом виде уже реализованы внутри Adobe FrameMaker и умеют оперировать с структурными документами заранее описанных типов, предпочтительным является вариант создания собственного типа структурных приложений Adobe FrameMaker, а не импортирование каждый раз при произведении импортировния соответствующего EDD. Также впользу этого способа говорит то, что функции импортирования и экспортирования Adobe FrameMaker позволяют всоответствии с описанием разбивать XML-документы на главы книги при импортировании и собирать главы книги в единый файл при экспортировании.

Описание структуры документов (также называемое структурным приложнием Adobe FrameMaker) состоит из шаблона документа, правил чтения и записи, DTD для XML-файлов, соответсвующих документам Adobe FrameMaker этого типа.

Шаблон документа явлется пустым документом (или частично созданным, тогда при создании нового документа такого типа уже определенн)ая его часть будет реализована) с импортированным в него EDD. Соответственно, для создания шаблона сначала требуется создать само EDD, а уже после этого импортировать его в пустой документ. Структура docline-документа, описанная на тот момент в rng-файле (Relax NG - язык описания структуры XML-файлов, основывающийся на XML вотличие от DTD), в таком виде, как она была представлена, была не переносима во Adobe FrameMaker, посколку она содержала своего рода шаблоны элементов, которые можно использовать в описании, но которые не отображаются в структуре XML-документа, которому соответствует это описание. В Adobe FrameMaker каждый элемент должен присутствовать в структуре, и следовательно было принято решение просто подставить всё содержание шаблонов в места их использования. Но тут появляется ещё одна проблема - в описании шаблоны рекурсивно используют друг друга и сами себя. Подстановка шаблонов не может сохранить эту рекурсию и подстановкой было реализовано несколько первых уровней рекурсии, остальные уровни вложенности DocLine и DocBook в плагине не поддерживаются. Средство для создания EDD Adobe Framemaker также не поддерживает взятие верхнеуровневых элементов из других EDD, а по описанию docline документ содержит в себе DocBook, как часть для создания статических частей документации, следовательно потребовалось скопировать всё EDD DocBook в EDD DocLine.

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

DTD (Data Table Definitions) - описание структуры XML-файлов определенного типа. Adobe FrameMaker предоставляет возможность сгенерировать по готовому EDD DTD-файл. EDD структурного приложения Docline включает в себя EDD стуктурного приложения DocBook, для которого существуют свои собственные правила чтения/записи и свой собственный DTD-файл, имеющий довольно сложную структуру и созданный отдельно от EDD. Следовательно, сгенерированное по EDD Docline DTD в части, касающейся DocBook, не будет удовлетворять спецификации DocBook или придется переписывать уже готовые правила чтения/записи структурного приложения DocBook, и совсем не гарантировано, что при этом XML-документы, соответствующие документам Adobe FrameMaker будут валидными (опять же в описании структуры DocBook в виде DTD существуют шаблоны, не являющиеся элементамив структуре). Поэтому по готовому EDD DocLine был сгенерирован DTD-файл, часть которого после этого была заменена на DTD DocBook. Следовательно потребовалось добавить в правила чтения/записи правила чтения/записи DocBook.

5Результаты


  1. Разработано представление структуры DRL-документов внутри Adobe FrameMaker.

    Верхний уровень иерархии - элемент DocLine

    Элементы второго уровня могут быть трех типов

    1. ProductLine

    2. DocumentationCore

    3. ProductDocumentation

      Элементы последующих уровней определяются взависимости от описания структуры и их положения в иерархии.

      Первые два уровня документации находятся в книге. В это же время второй уровень находится и в каждой из компонент книги, являясь при этом верхнеуровнемым элементом этого документа. Все последующие уровни находятся внутри конкретных документов. Для каждого элемента второго уровня помимо аттрибутов, необходимых для DRL-документа также требуется обязательный дополнительный аттрибут FileName, задающий имя файла, с которым сохранится данный документ после экспортирования.





  1. Реализовано открытие документов Adobe FrameMaker, соответсвующих языку DRL - с проверкой соответствия и без неё.

  2. Реализованы механизмы импортирования и экспортирования документов Adobe FrameMaker, соответствующих языку DRL

  3. Также реализованы задачи других учасников проекта: разработка интефейса взаимодействия с плагином внутри Adobe FrameMaker, механизмы проверки целостности и публикации.

6Проблемы


  1. Существуют реализации Adobe FrameMaker под разные платформы, но при этом

    1. FDK (Adobe FrameMaker API, Framemaker Developer's Kit) не поддерживает некоторые (в том числе и все 64-битные) платформы

    2. Реализация плагина, который работает под разными платформами, является более сложной задачей. Большое колличество времени было уделено настройке работоспособности плагины под разными платформами.

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

  3. Низкая скорость работы базовых операций с документацией засчет большого колличества обращений к жесткому диску.

  4. Не удалось решить проблему открытия диалога выбора имени промежуточных книг при импортировании.

  5. Нестабильная работа Adobe FrameMaker.

7Заключение


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

8Список литературы


  1. К.Ю.Романовский, Д.В.Кознов «Язык DRL для проектирования и разработки документации семейств программных продуктов». Вестник СПбГУ.сер. 10, 2007, вып. 4

  2. Adobe Solutions Network. FDK 7.0 Programmer’s Guide

  3. Adobe Solutions Network. FDK 7.0 Programmer’s Reference

Добавить документ в свой блог или на сайт

Похожие:

Гост 103-68 Единая система конструкторской документации. Стадии разработки
Настоящий стандарт устанавливает стадии разработки конструкторской документации изделий всех отраслей промышленности и этапы выполнения...

Гост 109-73 Единая система конструкторской документации. Основные требования к чертежам
Настоящий стандарт устанавливает основные требования к выполнению чертежей деталей, сборочных, габаритных и монтажных на стадии разработки...

Урок по теме: «Выделение фрагмента изображения и работа с ним в программе «Adobe Photoshop»
Цель занятия: Обобщить опыт работы над фрагментом изображения в программе «Adobe Photoshop»

Разработка системы визуального проектирования документации семейств программных продуктов
Разработка семейств программных продуктов – популярный и потенциально чрезвычайно эффективный метод разработки по, позволяющий повторно...

Разработка системы визуального проектирования документации семейств программных продуктов
Разработка семейств программных продуктов – популярный и потенциально чрезвычайно эффективный метод разработки по, позволяющий повторно...

Данный файл содержит основные ссылки на документации, книги и т д....

План: Введение Задание на разработку Обзор современных ajax-фреймворков
Целью разработки является создание конкурентноспособного редактора таможенных документов, взаимодействующего с системой Электронного...

План: Введение Задание на разработку Обзор современных ajax-фреймворков
Целью разработки является создание конкурентноспособного редактора таможенных документов, взаимодействующего с системой Электронного...

Стандарт разработки приложений на языке Java
Данный документ распространяется на условиях Лицензии свободной документации gnu (gnu fdl), Версия 3

Конспект интегрированной непосредственно-образовательной деятельности...
Интеграция образовательных областей: «Познание», «Физическая культура», «Здоровье», «Безопасность», «Художественное творчество»,...

Вы можете разместить ссылку на наш сайт:
Школьные материалы


При копировании материала укажите ссылку © 2013
контакты
odtdocs.ru
Главная страница