77226

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

Курсовая

Информатика, кибернетика и программирование

Цель данного проекта - разработать и реализовать плагин к Adobe FrameMaker, предоставляющий конечному пользователю удобный инструментарий среды FrameMaker для работы с технологией DocLine.

Русский

2015-02-02

405.5 KB

1 чел.

Санкт-Петербургский Государственный Университет

Математико-механический факультет

Кафедра системного программирования


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

Курсовая работа студента 444 группы
Дорохова Вадима Александровича

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

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

2009


Оглавление


[1]
Оглавление

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

[3] Контекст

[4] Обзор существующих средств создания документации

[5] Результаты

[6] Проблемы

[7] Заключение

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

Введение

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

Это явление не обошло стороной и сферу программной индустрии. Документация, как правило, сопровождает отдельные приложения или же целые семейства программных продуктов (product line []) на всех стадиях – от разработки до использования. Однако чтобы написать подробную и полную документацию часто приходится потратить много времени и сил. Ни для кого не секрет, что написание комментариев в исходных кодах, создание справочных систем и другой документации может занимать большую часть времени разработки всего программного продукта. Поэтому вполне логичным является стремление упростить процесс создания этой документации.

Специально для проектирования и разработки документации с акцентом на повторное использование был создан язык DRL (Document Reuse Language) []. Этот язык ориентирован на написание документации к целому семейству программных продуктов [], что делает возможным создание справочных систем к ряду похожих продуктов не вручную, не с помощью метода Copy/Paste, а автоматически, путем обнаружения более сложных зависимостей и связей.

Язык DRL и технология DocLine разрабатывались, чтобы упростить процесс создания документации, поэтому немаловажным также является вопрос удобства работы с технологией DocLine. Большинство технических писателей работают с издательской системой Adobe FrameMaker [], основанной на структурированной разметке документа (SGML, HTML, XML), и в связи с этим возникла задача интеграции технологии DocLine с этой системой таким образом, чтобы совместить возможности технологии DocLine с удобным инструментарием среды FrameMaker.

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

Цель данного проекта - разработать и реализовать плагин к Adobe FrameMaker, предоставляющий конечному пользователю удобный инструментарий среды FrameMaker для работы с технологией DocLine.

В рамках данного проекта моя задача состоит в следующем:

  1.  Обучение новым технологиям
    1.  Получить навыки работы с Adobe FrameMaker 8.0.
    2.  Получить навыки работы с FrameMaker 8.0 Developer Kit (8.0 FDK)
  2.  Разработка концепции
    1.  Разработать иерархию элементов DocLine в условиях работы в среде Adobe FrameMaker.

Документы Adobe FrameMaker имеют довольно простую иерархию: книги (Books) и вложенные в них документы (Documents). Поэтому возникла задача, как многоуровневую иерархию документов DocLine использовать в FrameMaker.

  1.  Определить требования к функциональности плагина.
  2.  Реализация плагина.
    1.  Реализация функциональности плагина, отвечающей за создание нового проекта DocLine и работу с ним.
    2.  Реализация функциональности плагина, отвечающей за добавление новых частей к уже существующему проекту DocLine.
    3.  Реализация функциональности плагина, отвечающей за сохранение и закрытие активного проекта.
    4.  Разработка и реализация внешнего вида меню плагина.
    5.  Разработка и реализация внешнего вида проекта. Написание CSS.
  3.  Интеграция с другими участниками проекта с целью создания единого рабочего плагина.
  4.  Контекст

Документ (Document) Adobe FrameMaker представляет собой файл, в котором хранится какая-либо информация. Документы бывают двух типов.

  •  Структурные.

Документ с XML-структурой, задаваемой пользователем, в каждом блоке которой может содержаться какая-либо информация.

  •  Неструктурные.

Документ без XML-структуры. Верстка такого документа происходит в режиме WYSIWYG.

В данном проекте мы будем иметь дело только со структурными документами, имеющими структуру, описанную в спецификации языка DRL.

Рис.1. Документ Adobe FrameMaker, окно Structure View, отображающее структуру документа, и окно Elements, показывающее элементы спецификации DRL, доступные для вставки в указанном месте.

Книга (Book) Adobe FrameMaker представляет собой файл, который связывает документы FrameMaker вместе. Книги также бывают структурные и неструктурные.

  •  Структурные книги имеют XML структуру, задаваемую пользователем. В качестве ссылок на конкретные документы выступают элементы заданной структуры.
  •  Неструктурные книги представляют собой простой список из ссылок на документы.

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

В данном проекте мы будем рассматривать только структурные книги.

Рис.2. Книга Adobe FrameMaker, окно Structure View, отображающее структуру книги и ссылки на документы FrameMaker, а также окно Elements, показывающее элементы спецификации DRL, доступные для вставки в указанном месте.

Опишем некоторые термины, используемые в данном проекте.

Импорт – процесс преобразования документации на языке DRL [] к проекту документации в Adobe FrameMaker. При этом XML-структура документации останется, но будет разбита по документам и книгам.

Экспорт - преобразование документации из проекта Adobe FrameMaker к документации на языке DRL [].

Публикация – процесс преобразования документации из проекта Adobe FrameMaker к конечному формату, такому, как HTML или PDF.

  1.  Обзор существующих средств создания документации

Так сложилось, что в России знают и используют три пакета верстки: QuarkXpress [], Adobe PageMaker [] и Microsoft Word []. Каждый из этих программных продуктов предназначен для решения строго определенных задач. Некоторые из пакетов верстки справляются с большими документами лучше, некоторые хуже, некоторые совсем не справляются. Однако всех их объединяет одно – они не предназначены для работы со структурированной информацией, а верстка происходит в режиме WYSIWYG.

Вот еще несколько программных средств и технологий, близких к предметной области.

  •  Author-IT []
    •  Хранит всю информацию как объекты в центральной базе данных и позволяет переиспользовать каждый из них.
    •  Поддерживает форматы RTF, PDF, MS Word, WinHELP, Sun JavaHelp, Oracle Help for Java, XML, DITA.
  •  LaTeX []
    •  Имеет широкий набор математических возможностей.
    •  Нет возможности переиспользования.
  •  DITA []
    •  Текст состоит из типизированных фрагментов (топиков), причем каждому типу соответствует свой тип описания (DTD).
    •  Карта – формализованное описание структуры.
    •  Любой фрагмент сплошного текста можно поместить в любой документ на любой уровень.
    •  Тема (topic) – основная единица информации
    •  Concept, Task, Reference – специализированные типы тем
    •  Map – организует темы в последовательность. Представляет собой коллекцию ссылок на топики (topicref).
    •  Conref – возможность многократного использования содержимого.

Все из вышеперечисленных программных средств либо имеют скудный функционал по сравнению с технологией DocLine, либо не ориентированы на разработку документации с упором на повторное использование. Поэтому вопрос об интеграции технологии DocLine именно с продуктом Adobe FrameMaker, основанным на структурированной разметке документа, актуален.

  1.  Результаты

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

  1.  Разработана иерархия элементов DocLine внутри проекта Adobe FrameMaker

Книги будут иметь следующую структуру: элемент верхнего уровня “DocLine”, в них могут быть вложены элементы DocumentationCore, ProductDocumentation, ProductLine. Все потомки этих трех элементов будут являться ссылками на конкретные документы, содержащие в себе всю остальную информацию. Таким образом, к примеру, потомок DocumentationCoreInfElement в книге будет являться ссылкой на соответствующий документ InfElement.

Документы будут представлять элементы следующих типов:

  •  Для раздела DocumentationCore:
    •  Dictionary
    •  Directory
    •  DirTemplate
    •  InfElement
    •  InfProduct
  •  Для раздела ProductDocumentation:
    •  Dictionary
    •  Directory
    •  DirTemplate
    •  FinalInfProduct
  •  Для раздела ProductLine
    •  Product

Все эти файлы будут иметь структуру, описанную в спецификации языка DRL. Верхний элемент для них будет определяться их типом. К примеру, в документе InfElement и верхний элемент будет InfElement.

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

  1.  Определены требования к функциональности плагина.

Функциональность плагина должна включать в себя следующие возможности.

  1.  Создание новых проектов DocLine и добавление к ним компонентов (создаются как документы FrameMaker со структурой DocLine)
    1.  Поддержка уже созданных проектов DocLine (открытие, добавление новых элементов, сохранение).
    2.  Импорт проекта из документации на языке DRL.
    3.  Экспорт проекта в документацию на языке DRL.
    4.  Публикация проекта в конечном формате (HTML, PDF).
    5.  Проверка корректности проекта.
    6.  Закрытие текущего проекта.
  2.  Реализована функциональность плагина, отвечающая за создание нового проекта и работу с ним, а также добавление новых элементов в уже созданный проект.

Есть возможность создавать новый проект, добавлять в него новые разделы DocumentationCore, ProductDocumentation, ProductLine, а также конкретные документы (InfElement, InfProduct и т.п.) как их потомки.

  1.  Реализована функциональность плагина, отвечающая за закрытие активного проекта.

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

  1.  Разработан внешний вид меню плагина.

Плагин встраивается в Adobe FrameMaker как новый элемент главного меню, названный DocLine. Этот элемент меню может содержать в себе различные наборы команды, в зависимости от типа активного документа.

  •  Если нет открытых файлов, или активен файл типа Document, то меню содержит команды для создания нового проекта, открытия уже существующего, импорта проекта из документации DRL, экспорта и закрытия проекта.

  •  Если активен файл типа Book, то меню содержит больший набор команд: есть команды для создания нового проекта, работы с ним (добавление конкретных разделов, элементов в разделы), открытие проекта, импорт, публикация, экспорт, проверка корректности и закрытие активного проекта.

  1.  Разработан шаблон документа, по которому создаются все элементы третьего уровня (Dictionary, Directory и т.п.)

В заголовке шаблона указан тип элемента и его атрибут Name. Это поле генерируется автоматически при создании элемента и представляет собой подложку, то есть фон документа, благодаря чему никак не влияет на основной поток текста. При экспорте заголовок игнорируется. Такой стиль отображения создан для удобства работы пользователя.

Плагин был реализован на языке C с использованием Frame Application Program Interface (API) и Frame Development Environment (FDE) [].

  1.  Проблемы

Среди трудностей, с которыми пришлось столкнуться в ходе данной курсовой работы, можно выделить:

  •  отсутствие электронной справочной системы по Frame API;
  •  в проекте участвовали несколько человек, и все они работают под разными операционными системами. Это значительно усложнило процесс интеграции внутри команды, но зато позволило протестировать плагин в Windows XP, Windows XP 64bit, Windows Vista, а также Windows 7 RC1.
  1.  Заключение

Задача выполнена на 80%. С одной стороны, реализована необходимая функциональность. Есть возможность создания нового проекта, работы с существующим проектом. Есть возможность импорта/экспорта. Однако, с другой стороны, нельзя сказать, что результат полностью меня устраивает. В ходе тестирования система Adobe FrameMaker зарекомендовала себя как крайне нестабильная, постоянно зависала и вызывала ошибки. Кроме этого, из-за особенностей реализации Adobe FrameMaker простая документация размером 10-15 документов по несколько страниц в каждом документе на современных компьютерах с двухъядерными процессорами собирается больше минуты, что никак не может способствовать удобству работы с документацией.

Еще одной примечательной особенностью стало то, что Adobe позиционирует свой FDK (FrameMaker Developer Kit) как средство для создания кроссплатформенных приложений для FrameMaker, однако на деле мне и другим участникам проекта пришлось потратить немало времени на то, чтобы плагин заработал одинаково на всех компьютерах разработчиков. Большую часть времени проект существовал по принципу «я написал этот код, у меня он и работает».

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

http://en.wikipedia.org/wiki/Product_line

  1.  Издательская система Adobe FrameMaker

http://www.adobe.com/products/framemaker/

  1.  Adobe FrameMaker Developer Kit

http://www.adobe.com/devnet/framemaker/fdk/9/

  1.  FrameMaker Developer Knowledgebase

http://support.adobe.com/devsup/devsup.nsf/framekb.htm

  1.  Quark XPress 

http://www.quark.com/ 

  1.  Adobe PageMaker 

http://www.adobe.com/products/pagemaker/ 

  1.  Microsoft Word

http://office.microsoft.com/en-us/word/FX100649251033.aspx

  1.  Author-IT

http://www.stcsig.org/ss/articles062002/6_02_ss_authorit.htm 

http://www.author-it.com/ 

  1.  LaTeX

http://www.latex-project.org/ 

  1.  DITA

http://wiki.techwriters.ru/index.php?title=FAQ_Dita 

http://www.philosoft.ru/index.php?topic=dita-intro


 

А также другие работы, которые могут Вас заинтересовать

72795. Проектирование домостроительного комбината мощностью 140 тыс. м3 в год в Воронежской области 659.5 KB
  Основным видом продукции являются наружные панели стеновые трехслойные железобетонные. Стеновые панели бетонные железобетонные используются в качестве строительного материала в домостроении. По назначению панели бывают: для надземных гаражей для цокольных этажей или для чердаков.
72797. Назначение, сущность, основные составляющие и эволюция инновационного менеджмента 480.5 KB
  Инновация определяется в нем прежде всего как конечный результат инновационной деятельности как прогрессивное новшество которое проявляется либо в виде продукта либо в виде технологических процессов новых методов организации и управления производством.
72798. ПОЖАРНАЯ БЕЗОПАСНОСТЬ В СТРОИТЕЛЬСТВЕ 961.5 KB
  Зачастую используется документация не подвергшаяся экспертизе в органах надзорной деятельности что затрудняет и осложняет обеспечение противопожарной защиты на возводимых зданиях и сооружениях.