2.1 Импорт компьютерной документации форматов HTML и CHM

СОДЕРЖАНИЕ
ВВЕДЕНИЕ .............................................................................................................. 3
1.2 Компьютерная документация: назначение................................................ 3
1.2 Выбор формата хранения компьютерной документации ........................ 4
ПРОЕКТИРОВАНИЕ И АНАЛИЗ ПРЕДМЕТНОЙ ОБЛАСТИ ........................ 9
2.1 Импорт компьютерной документации форматов HTML и CHM ............. 9
2.2 Модификация компьютерной документации ......................................... 10
2.3 Автоматизация конвертирования и модификации компьютерной
документации. .................................................................................................... 11
2.4 Конвертирование компьютерной документации в формат CHM ........ 11
2.4.1 Проектный файл ................................................................................... 12
2.4.2 Параметры секции OPTIONS ............................................................. 13
2.4.3 Секция FILES ....................................................................................... 14
2.4.4 Оглавление и предметный указатель ................................................... 14
2.5 Модульная структура ................................................................................ 17
2.5.1 Модуль конфигурации .......................................................................... 18
2.5.2 Модуль генерации CHM-файла.......................................................... 18
2.5.3 Модуль модификации содержания документации........................... 19
2.5.4 Модуль модификации оглавления документации .............................. 20
3.1 Модуль конфигурации .............................................................................. 21
3.2
Модуль генерации CHM файлов............................................................. 29
3.3
Модуль модификации содержания документации ............................... 32
3.4
Модуль модификации оглавления документации ................................ 40
3.5
Модуль конвертирования источника во внутреннее представление .. 43
ЗАКЛЮЧЕНИЕ ..................................................................................................... 47
СПИСОК ЛИТЕРАТУРЫ .................................................................................... 48
ПРИЛОЖЕНИЕ ..................................................................................................... 50
Пример конфигурации ....................................................................................... 50
ВВЕДЕНИЕ
Процессы разработки (сопровождения и т.д.) документации всегда и
везде идут плечом к плечу с процессами разработки изделий, программных
изделий, создания автоматизированных систем. В крупных компаниях в
процессе
разработки
документации
задействовано,
как
правило,
значительное число специалистов различных подразделений. В мелких и
средних компаниях техническая документация «составляется» узким кругом
лиц, именующих себя техническими писателями.
Как бы то ни было, для большинства компаний процесс разработки
(сопровождения и т.д.) документации остается занятием в немалой степени
рутинным, трудоемким и ресурсоемким и, как правило, неблагодарным по
отношению к непосредственным исполнителям.
1.2 Компьютерная документация: назначение
С каждым годом компьютерная информация играет все более важную
роль в нашей жизни. Чем больше справочного материала в распоряжении
пользователя, тем спокойнее он должен себя чувствовать. Но обилие
материалов порождает другую проблему: как обеспечить пользователю
быстрый и удобный доступ к конкретной теме, к конкретному термину и т.д.
Создание электронной документации уже длительное время базируется на
технологии гипертекста. Одно из важнейших его достоинств − наличие
интерактивных ссылок, которые позволяют читателю перемещаться между
темами почти в произвольном порядке. «Почти», потому что на самом деле
3
возможные переходы определяются навигационной структурой документа,
предложенной его создателем. Кроме того, определенные особенности в
работе с документом обусловлены спецификой конкретного гипертекстового
формата.
1.2 Выбор формата хранения компьютерной документации
В
настоящее
применяются
около
время
для
десятка
создания
компьютерных
различных
форматов,
документов
включая
PDF
(Portable Document Format), RTF (Rich Text Format), DOC (Document Word) и
WinHelp (Windows Help), а также целое семейство языков гипертекстовой
разметки,
самыми
популярными
из
которых
можно
считать HTML
(Hypertext Markup Language) и XML (eXtensible Markup Language). Сюда же
следует добавить и специализированный формат CHM (Compiled HTML).
Однако далеко не все из существующих форматов пригодны для создания
справочников.
Причины
разные:
одни
форматы
не
обеспечивают
приемлемую компактность итогового документа, другие не обладают
достаточной функциональностью и выразительностью, третьи требуют
установки
на
компьютеры
пользователей
дополнительного
(причем
дорогостоящего) программного обеспечения.
Одним из самых распространенных форматов документации является
формат CHM. Множество компьютерных приложений имеют справочную
документацию в этом формате.
Преимущества формата CHM:
1. Не требует специальных программ для просмотра. Это стандартный
формат операционных систем семейства Windows. Файлы данного
4
формата могут содержать в себе разнообразные элементы: элементы
навигации, текст, FLASH (Adobe Flash), видео, музыку и другие
элементы.
2. Наличие навигационного меню, расположенного наряду с окном
просмотра, по которому можно с легкостью перемещаться по
разделам.
3. Размер файла. Обычный текстовый формат, DJVU или PDF занимает
большее место в сравнении с тем же содержимым, но в формате
CHM-файла.
4. Доступность всех возможностей форматирования, которые есть в
HTML и CSS.
5. Возможность полнотекстового поиска.
6. Возможность просмотра множества CHM-файлов в виде единого
файла с общим содержанием и предметным указателем (в частности,
ранняя версия MSDN Library предоставлялись в формате HTMLHelp).
7. Легкая
интегрируемость
с
программным
кодом
создаваемого
приложения.
1.3 Существующие решения
Часто возникает задача
модификации документации.
На текущий
момент времени существуют приложения, позволяющие автоматизировать
сборку и модификацию документации в формате CHM. Проведем анализ
таких приложений. Для этого выделим ключевые параметры:
1. Импорт документации форматов CHM и HTML.
2. Корректность
построения
оглавления
HTML-документации.
5
при
импорте
3. Фильтрация и изменение содержания документации.
4. Возможность добавления и изменения навигационной панели.
5. Стоимость.
6. Обновления и техническая поддержка.
7. Импорт индексов из CHM-файлов.
8. Скорость конвертирования документации.
9. Размер дистрибутива приложения.
Приложения
протестированы
на
системе
со
следующими
характеристиками:
AMD Phenom™ X4 Quad-Core Processor GP-9500 2.20 GHz, 4 GB.
На основе вышеперечисленных параметров проведено сравнение
следующих компьютерных программ:
 DocToHelp (http://www.doctohelp.com);
 ActoStudio (http://www.softarex.com);
 Dr. Explain (http://www.softarex.com).
Результаты представлены в таблице 1.
Таблица 1
Характеристика
Импорт
DocToHelp
ActoStudio
Dr. Explain
документов не поддерживает импорт
форматов CHM и HTML
нет
импорт
документации
документов
форматов CHM
формата CHM
и
HTML
возможен
Корректность построения оглавление
оглавления
оглавления при импорте строится
HTML документации
не строится
корректно
6
не нет
Продолжение таблицы 1
Фильтрация и изменение фильтрация
содержания
содержания
документации
отсутствует
добавлять Нет
Возможность
или
Нет
нет
Нет
есть
возможность
изменять
добавления
навигационную панель
навигационной
панели
1300 долларов
Стоимость
393.34 евро
минимальная
стоимость
165
долларов
и Да
Обновления
Да
да
техническая поддержка
Импорт
индексов
при нет,
импорте CHM файлов
так
как нет
нет
отсутствует
импорт
CHM
файлов
конвертации 25 минут
Скорость
объемной
2-3 минуты
не
тестировалось,
документации
так
формата CHM
как
нет
возможности
импорта
CHM
файлов
Размер
дистрибутива 81,5 МБ
43,2 МБ
28,7 МБ
приложения
Рассмотренные программы являются мощными решениями для работы
с документацией, реализуют большой набор функций для создания и
конвертирования компьютерной документацией, однако интересующие нас
функции они не реализуют либо реализуют, но не полностью.
7
Из приведенного анализа следует вывод о необходимости разработки
собственного программного решения, отвечающего нашим требованиям. Это
решение должно выполнять следующие задачи:
1. Импорт компьютерной документации форматов HTML и CHM с
возможностью получения оглавления и индексного файла из исходной
документации.
2. Модификация содержания и оглавления компьютерной документации.
3. Фильтрация файлов оглавления компьютерной документации.
4. Автоматизация процесса конвертирования и модификации компьютерной
документации.
5. Генерация файлов проекта, индексного файла и файла оглавления
форматов HHP, HHK и HHC соответственно для компиляции HTML
страниц в единый CHM-файл.
В
магистерской
диссертации
была
разработана
библиотека
SomeToCHM для модификации и конвертирования документов форматов
HTML и CHM в формат CHM. В сети Интернет опубликована web-страница
с описанием реализованной библиотеки (http://code.google.com/p/html2chm).
8
ПРОЕКТИРОВАНИЕ И АНАЛИЗ ПРЕДМЕТНОЙ ОБЛАСТИ
2.1 Импорт компьютерной документации форматов HTML и CHM
В задачу импорта компьютерной документации форматов HTML и
CHM входит:
1. Импорт файлов оглавления.
2. Импорт индексных файлов.
3. Импорт страниц документации.
Импорт компьютерной документации осуществляется в два этапа.
Сначала происходит распаковка CHM-файла. В результате получаем набор
HTML-страниц. При этом если CHM-документ содержал индексы, то после
распаковки становится доступным индексный файл формата HHK. Такой
файл содержит описание индексов на языке HTML и не придерживается
стандарту Extensible Hypertext Markup Language (XHTML − расширяемый
язык разметки гипертекста). Также становится доступным файл оглавления
формата HHC. Оглавление − это указатель заголовков документации. Его
именуют TOC-файлом (Table of Contents). Он так же, как и индексный файл,
имеет структуру HTML-документа. Второй этап: импорт HTML-страниц, в
этом случае оглавление содержится на одной из HTML-страниц, которую
необходимо импортировать.
Так как любой HTML-документ можно представить в виде DOM
модели (Document Object Model − «объектная модель документа»), то было
бы удобней работать не с текстовым представлением документа, а его DOM
моделью. Для этого использована библиотека Html Agility Pack (HAP) версии
1.4.0 (http://htmlagilitypack.codeplex.com). Эта библиотека позволяет читать и
9
модифицировать DOM-модель HTML-документов и поддерживает запросы
на языке XML PATH Language (XPATH), она бесплатная и постоянно
обновляется. XPATH − это язык запросов к элементам XML-подобного
документа.
Как правило, документы формата HTML содержат помимо текста
различные мультимедиа файлы, файлы стилей и другие. Важно, чтобы все
используемые
файлы
в
документах
также
были
импортированы
в
результирующую документацию.
2.2 Модификация компьютерной документации
Задача модификации документации состоит из следующих подзадач:
1. Настройка
стилей
HTML-документации:
изменение,
удаление
существующих и добавление новых стилей.
2. Форматирование страниц документации с помощью HTML-шаблонов.
3. Фильтрация оглавления документации. При этом важно, чтобы после
фильтрации HTML-страницы не содержали битых ссылок. Также
необходимо, чтобы размер выходного CHM-файла после фильтрации и
модификации, не увеличился. Для этого, в частности, необходимо
учесть какие HTML-страницы после фильтрации в результирующий
CHM файл больше не войдут. Индексный файл также необходимо
скорректировать после фильтрации оглавления.
4. Удаление и замена элементов страниц по указанным строкам и по
запросам на языке XPATH.
5. Настройка
навигации
по
связанным
удаление и замена навигационной панели.
10
страницам
документации:
6. Модификация заголовков оглавления: удаление нумерации, удаление
и замена строк в заголовках.
2.3 Автоматизация конвертирования и модификации компьютерной
документации.
Чтобы настройку конвертирования документации не производить
заново необходимо её где-то хранить, для этой цели используется файлы
проекта. Файл проекта представляет собой файл, хранящий в себе настройки
конвертирования
и
модификации
документации
в
удобном
для
пользователей формате. Пользователь, однажды настроив проектный файл,
использует его каждый раз для получения документации.
2.4 Конвертирование компьютерной документации в формат CHM
После модификации HTML-документов происходит сборка их в файл
формата CHM. Для получения CHM файла достаточным условием является
наличие файлов HHK, HHC и HHP. То есть требуется создать индексный
файл (HHK), файл оглавления (HHC), и затем, на их основе получить
проектный файл
формата HHP. И с помощью программы hhc.exe
(MS HTML Help Compiler Location) из входного файла проекта генерируется
CHM-документ.
11
2.4.1 Проектный файл
Файл проекта является основным для компиляции в CHM-формат, он
имеет формат HHP и описывает опции компиляции, также содержит ссылки
на все другие файлы, участвующие в сборке. Пример его представлен на
листинге 1.
Листинг 1
[OPTIONS]
Binary Index=No
Compatibility=1.1 or later
Compiled file=Foo.chm
Contents file=Foo.hhc
Default Window=main
Default topic=Foo.htm
Display compile progress=No
Index file=Foo.hhk
Language=0x419 Русский
Title=Foo Title
[WINDOWS]
main=,"Foo.hhc","Foo.hhk","Foo.htm","Foo.htm",,,,,0x72520,,0x60305e,[112,11,896,658],0x100b00
00,,,,,,0
[FILES]
HTML\Manual.
12
2.4.2 Параметры секции OPTIONS
Рассмотрим
параметры
секции
[OPTIONS]
проектного
файла.
Описание параметров приведено в Таблице 2.
Таблица 2
Имя параметра
Compatibility
Описание
определяет совместимость полученного CHM-файла с программой
просмотра (HH.EXE). Рекомендуемое значение версия 1.1.
Compiled file
имя итогового CHM-файла.
Contents file
имя файла содержания.
Default window
название окна, в котором откроется справка во время просмотра.
Default topic – страница справки, которая будет активна сразу после
открытия файла.
Error log file
имя файла, в который будут сохраняться сообщения, выдаваемые
программой при компиляции проекта. Является не обязательным
параметром.
Full-text search
параметр,
определяющий
отображение
вкладки
"Поиск"
и,
соответственно, возможность полнотекстового поиска по файлу
справки. Возможные значения: Yes, No.
Index file
определяет имя файла Индекса. Указывается в случае наличия
вкладки Индекс и/или Поиск.
Language
язык компиляции. Для проектов, содержащих русские названия
страниц, необходимо указывать Русский.
13
2.4.3 Секция FILES
В данной секции указываются все файлы HTML-страниц, входящих в
документацию. Здесь также необходимо указать файлы, которые должны
войти в документацию, в том числе изображения, файлы стилей,
использующихся на HTML-страницах.
2.4.4 Оглавление и предметный указатель
Оглавление документации содержится в HHC-файле. Структура
оглавления − иерархическая, каждый элемент имеет своё имя, иконку. К
элементу оглавления может быть привязана одна или несколько тем
(HTML-файлов). Предметный указатель хранится в HHK-файле.
Пример содержания HHC-файла приведен на листинге 2.
Листинг 2
<!DOCTYPE HTML PUBLIC "-//IETF/DTD HTML/EN">
<HTML>
<HEAD>
<meta name="GENERATOR" content="Foo generator"></HEAD>
<BODY>
<OBJECT type="text/site properties">
<param name="FrameName" value="right">
<param name="ImageType" value="Folder">
<param name="Window Styles" value="0x27">
<param name="Foreground" value="0x80000005">
14
Продолжение листинга 2
<param name="Background" value="0x80000005">
<param name="Background" value="0x80000005">
<param name="Font" value="MS Sans Serif,8,0">
</OBJECT>
<UL>
<LI>
<OBJECT type="text/sitemap">
<param name="Name" value="Foo">
<param name="Name" value="Foo">
<param name="Local" value="foo.php">
<param name="ImageNumber" value="12">
</OBJECT>
<UL>
<LI>
<OBJECT type="text/sitemap">
<param name="Name" value="Boo">
<param name="Local" value="boo.php">
<param name="ImageNumber" value="11">
</OBJECT>
</UL>
</UL>
</BODY>
</HTML>
Первая строка документа определяет схему разметки документа. Далее
идут строки стандартные для любого HTML-файла. Параметр «Window
Styles» − определяет стиль окна панели навигации для программы просмотра.
Каждый заголовок раздела в этом файле представлен в виде тегов
<OBJECT></OBJECT>,
между
которыми
заключаются
параметры,
определяющие имя, название файла и иконку данного раздела в панели
15
навигации. Все имена разделов заключены в список (тегами <UL></UL>).
Если какой-либо раздел имеет подразделы, то они заключаются в отдельный
список.
Файл HHK создается, если необходимо отобразить вкладку «Индекс»
панели навигации. Пример содержания файла индекса представлено на
листинге 3.
Листинг 3
<!DOCTYPE HTML PUBLIC "-//IETF/DTD HTML/EN">
<HTML>
<HEAD>
<meta name="GENERATOR" content="Foo generator">
</HEAD>
<BODY>
<OBJECT type="text/site properties"></OBJECT>
<UL>
<LI>
<OBJECT type="text/sitemap">
<param name="Keyword" value="Foo_keywords">
<param name="Local" value="foo.php">
</OBJECT>
<LI>
<OBJECT type="text/sitemap">
<param name="Keyword" value="Boo_keywords">
<param name="Local" value="boo.php">
</OBJECT>
</UL>
</BODY>
</HTML>
Структура этого файла аналогична структуре HHK-файла.
16
2.5 Модульная структура
Модуль конвертации и модификации документации форматов CHM и
HTML состоит из следующих основных компонентов:
1. Модуль конфигурации.
2. Модуль генерации CHM-файла.
3. Модуль модификации содержания документации.
4. Модуль модификации оглавления документации.
5. Модуль конвертирования источника во внутреннее представление.
На рисунке 1 представлена модульная структура библиотеки.
РИС 1
17
2.5.1 Модуль конфигурации
Данный модуль отвечает за загрузку и сохранение файлов проекта.
Модуль можно разделить на следующие компоненты:
1) компонент «валидации конфигурационного файла»;
2) компонент «загрузки и сохранения конфигурации».
Компонент «валидации конфигурации» выполняет функцию проверки
соответствия входного файла проекта формату файла конфигурации.
Компонент «загрузки и сохранения конфигурации» отвечает за загрузку и
сохранение
конфигурационного
файла,
предоставляет
необходимый
интерфейс, с помощью которого можно производить чтение параметров
конфигурации.
2.5.2 Модуль генерации CHM-файла
Данный модуль осуществляет построение CHM-файла. На вход модулю
приходит набор HTML-файлов, оглавление и индексный файл.
Модуль можно разделить на компоненты:
1) компонент «генерации файла проекта»;
2) компонент «генерации оглавления документации»;
3) компонент «генерации индексного файла».
Компонент «генерации файла проекта» производит генерацию файла
формата HHP, который является входным файлом программы hhc.exe
(MS HTML Help Compiler Location).
Hhc.exe из входного файла проекта
18
генерирует
CHM-документ.
На
вход
компонента
поступает
модель
проектного файла.
Компонент «генерации оглавления документации» по модели файла
оглавления строит HHC-файл. Под моделью понимается внутреннее
представление файла оглавления, с которым удобнее работать.
Компонент «генерации индексного файла» по модели индексного
файла строит HHK-файл.
2.5.3 Модуль модификации содержания документации
В разработанной системе существует два вида модификаторов
документации
−
это
модификаторы
оглавления
документации,
и
модификаторы содержания. Данный модуль отвечает за возможность
модификации содержания документации.
Одной из основных задач системы является возможность модификации
содержания HTML-страниц: возможность удалять или заменять элементы
страницы, применять шаблоны форматирования к страницам документации.
При этом для разной документации необходимо применять свой набор
модификаторов. Также необходимо иметь возможность расширить набор
модификаторов и указать порядок их применения.
Выделим основные функции модуля:
1. Замена одних строк на другие.
2. Замена HTML-узлов на указанный текст.
3. Удаление строк или узлов из документа.
4. Применение шаблонов форматирования к страницам документации.
19
2.5.4 Модуль модификации оглавления документации
Следующей,
важной
задачей
системы
является
модифицировать оглавление документации.
Выделим основные функции модуля:
1. Удаление заголовков оглавления.
2. Удаление нумерации из заголовков оглавления.
3. Замена и удаление элементов из заголовков оглавления.
20
возможность
РЕАЛИЗАЦИЯ
3.1 Модуль конфигурации
Данный модуль отвечает за чтение и сохранение параметров
конфигурации в файл проекта.
Вся конфигурация проекта содержится в классе ChmConfiguration,
который
включает методы, позволяющие осуществить чтение настроек
проекта из конфигурационного файла.
Чтобы получить доступ к информации о конфигурации проекта,
необходимо вызвать метод GetProject, который возвращает класс с
настройками проекта – ProjectSection.
Структура класс ChmConfiguration
представлена на рисунке 6.
РИС 2
Класс с настройками проекта – ProjectSection, предоставляет доступ к
различным секциям конфигурации:
21
1. TemplatesSection – содержит описание шаблонов.
2. ContentsSection – содержит параметры для распознавания содержания
документации.
3. MappingsSection – содержит описание привязки параметров файла
проектов между собой.
4. FiltresSection. – содержит набор фильтров, которые при сборке
документации будут применены к её оглавлению.
5. ModifiersSection – содержит набор модификаторов, которые будут
применены к содержанию документации.
Структура класса ProjectSection представлена на рисунке 7.
РИС 3
22
Для инкапсуляции доступа к конфигурационному файлу используется
следующий
набор
интерфейсов:
ITemplatesProvider,
IContentsProvider,
IFiltersProvider, IProjectsProvider. Данные интерфейсы реализуют модель
«поставщика настроек»,
«модель поставщика»
предназначена
для
инкапсуляции всей или части особенностей хранения конфигурации проекта.
Наиболее важным аспектом работы данных интерфейсов, является то,
что ни один класс в системе (кроме самого поставщика) не зависит о
конфигурационном файле, следовательно, чтобы изменить представление
конфигурационного файла достаточно заменить поставщика.
Интерфейс ITemplatesProvider предоставляет доступ к шаблонам
конфигурации. Структура интерфейса представлена на рисунке 8.
РИС 4
Интерфейс IContentsProvider предоставляет доступ к настройкам для
индексного файла и файла оглавления. Структура интерфейса представлена
на рисунке 9.
23
РИС 5
Интерфейс IFiltersProvider предоставляет доступ к модификаторам
документации. Структура интерфейса представлена на рисунке 10.
РИС 6
Интерфейс
IConfigurationProvider
наследуется
от
интерфейсов
ITemplatesProvider, IContentsProvider, IFiltresProvider, IProjectsProvider и
предоставляет API для работы с настройками проекта. Схема интерфейса
представлена на рисунке 11.
24
РИС 7
Общая схема классов представлена на рисунке 12.
РИС 8
Класс MappingsSection хранит настройки, касающиеся оформления
страниц документации. С помощью него задается соответствие страницы
документации и шаблонов, которые будут применёны к этой странице.
Пример конфигурирования секции MappingsSection
листинге 4.
25
представлен на
Листинг 4
<MappingsSection>
<TemplateMappings>
<TemplateMappingEntry>
<MappingType>[Only|Except]</MappingType>
<TemplateIds>
<string>value1</string>
<string>value2</string>
</TemplateIds>
<Paths>
<string>{path to pages}</string>
</Paths>
</TemplateMappingEntry>
</TemplateMappings>
</MappingsSection>
Класс TemplateMappingEntry хранит информацию о том, какие
шаблоны будут применены к страницам.
Объект класса TemplatesSection хранит данные о шаблонах, их
расположении и параметры. Вспомогательным классом для TemplateSection
является класс TemplateElement,
хранения
параметров
шаблона.
он является структурной единицей для
Пример
TemplateSection представлен на листинге 5.
26
конфигурирования
секции
Листинге 5
<TemplatesSection>
<Templates>
<TemplateElement>
<Source>С:/Templates</Source>
<SourceType>Path</SourceType>
<Id>{unic id}</Id>
<Type>
DelimiterTemplate
</Type>
</TemplateElement>
</Templates>
</TemplatesSection>
Класс ContentsSection
хранит данные о расположении файла
оглавления и индексного файла документации.
Пример секции ContentsSection представлен на листинге 6.
Листинг 6
<ContentsSection>
<TocFilePath>{path to table of contents}</TocFilePath>
<TocXPath>{xpath to content of table of contents}</TocXPath>
<IndexFilePath>{path to index file}</IndexFilePath>
<ContentsTags><string>{tag}</string></ContentsTags>
<ContainerTags>
<string>{tag}</string>
</ContainerTags>
<ListTags><string>{tag}</string></ListTags>
</ContentsSection>
27
Класс ModifiersSection хранит настройки модификации содержания
документации. В частности в нем содержится набор модификаторов для
содержания, оглавления и индексного файла документации. Пример секции
ModifiersSection приведен в листинге 7.
Листинг 7
<ModifiersSection>
<AfterFiltrateStrategies>
<ModifierStrategyElement Type="HtmlNodeRepairStrategy" />
<ModifierStrategyElement Type="HtmlNodeRemoveStrategy">
<InputParameters>
<StringList>
<StringValue>//table[@width='100%’]</StringValue>
<StringValue>//table[@border='0]</StringValue>
</StringList>
</InputParameters>
</ModifierStrategyElement>
<ModifierStrategyElement Type="PageBuilderStrategy" />
<ModifierStrategyElement Type="NavigationBarBuildStrategy" />
<ModifierStrategyElement Type="PathBuilderStrategy" />
</AfterFiltrateStrategies>
</ModifiersSection>
Класс FiltersSection хранит список фильтров, которые буду применены
для фильтрации оглавления документации. Пример этой секции приведён
в листинге 8.
28
Листинг 8
<FiltersSection>
<TableOfContentsFilters>
<FilterElement Type="IncludeTopicFilter">
<InputParameters>
<StringList>
<StringValue>12. Internal functions</StringValue>
<StringValue>sserw</StringValue>
</StringList>
</InputParameters>
</FilterElement>
<FilterElement Type="RemoveTopicFilter">
<InputParameters>
<StringList>
<StringValue>sdfsdf</StringValue>
</StringList>
</InputParameters>
</FilterElement>
</TableOfContentsFilters>
</FiltersSection>
3.2 Модуль генерации CHM файлов
Данный модуль
позволяет генерировать CHM-файлы и реализует
следующий набор функций:
1. Генерация индексного файла по внутреннему представлению. За
данную задачу отвечает класс IndexGenerator. Индексный файл представляет
29
собой файл формата HHK, который впоследствии будет использоваться для
генерации CHM-файла. Структура класса представлена на рисунке 13.
РИС 9
2. Генерация оглавления документации по внутреннему представлению.
За данную функцию отвечает класс TocGenerator. Файл оглавления – это
файл формата HHC, который будет использован для генерации CHM файла.
Структура класса представлена на рисунке 14.
РИС 10
30
3. Генерация файла проекта по внутреннему представлению. За данную
функцию отвечает класс ProjectGenerator. В результате генерируется файл
проекта формата HHP. Структура класса представлена на рисунке 15.
РИС 11
4. Генерация CHM-файла. За данную функциональность отвечает класс
ChmGenerator. Структура класса представлена на рисунке 15.
31
РИС 12
3.3 Модуль модификации содержания документации
Данный модуль отвечает за модификацию содержания документации.
Функции модуля:
1. Замена или удаление HTML-узлов в DOM-модели документации. Для
реализации разработан набор стратегий. Опишем основные стратегии.
2. Применение шаблонов к страницам документации.
Шаблоны делится на типы:
 шаблон панели навигации;
 шаблон навигационной панели;
 шаблон кнопки «вперёд»;
 шаблон кнопки «назад»;
 шаблон кнопки «домой».
32
За
функцию
замены
HTML
узлов
который
HtmlNodeReplaceByXPathStrategy,
отвечает
реализует
класс
интерфейс
IHtmlModifierStrategy. Схема класса представлена на рисунке 16.
РИС 13
Стратегия HtmlNodeRemoveStrategy отвечает за удаление HTML-узлов из
страниц
документации,
этот
класс
реализует
интерфейс
IHtmlModifierStrategy. Схема класса представлена на рисунке 17.
РИС 14
33
Пользователь может разработать свой собственный модификатор
HTML-страниц,
для
этого
необходимо
реализовать
интерфейс
IHtmlModifierStrategy (рисунок 18).
РИС 15
Параметр шаблона выглядят следующим образом: /*{ параметра}*/, где
«параметр» – имени параметра. Пример шаблона страницы с параметрами
приведён на листинге 9.
Листинг 9.
<html>
<head>
<title> The SQL Language</title>
<meta name="generator" content="Home brain" />
<meta name="keywords" content="" />
/*{metaCharset}*/
/*{metaLanguage}*/
<link type="text/css" href="styles.css" rel="stylesheet" />
/*{links}*/
/*{styles}*/
/*{scripts}*/
</head>
<body>
<table id="navigation">
<tr> <td>Navigation: /*{navigationPath}*/</td>
</tr>
<td>/*{navigationBar}*/</td>
</tr>
34
Продолжение листинга 9
</tr>
<tr><td colsapn=”2”>/*{pageHeader}*/</td></tr>
</table>
<div id="mainbody">
/*{pageContent}*/
</div>
</body>
</html>
Опишем параметры приведенного выше шаблона:
1) /*{metaCharset}*/ − кодировка HTML-страницы;
2) /*{metaLanguage}*/ − локаль HTML-страницы;
3) /*{links}*/ − подключаемые скрипты HTML-страницы;
4) /*{styles}*/ − подключаемые стили;
5) /*{scripts}*/ − вставки JavaScript кода;
6) /*{navigationPath}*/ параметр для вставки навигационного путь
страницы (breadcrumbs);
7) /*{navigationBar}*/ - параметр для вставки навигационной панели;
8) /*{pageHeader}*/ - заголовок страница;
9) /*{pageContent}*/ - содержание страницы.
Пример шаблона навигационной панели приведён на листинге 10.
35
Листинг 10
<table id="navigationBar">
<tr>
<td>
/*{previous|empty:<img src=”path to image” alt=”” />}*/
</td>
<td>
/*{home}*/
</td>
<td>
/*{next|empty:<img src=”path to image” alt=”” />}*/
</td>
<td>   </td>
</tr>
</table>
Опишем параметры этого шаблона:
 /*{previous|empty:<img src=”path to image” alt=”” />}*/ − параметр для
вставки шаблона кнопки «назад». Опция «empty» означает, что если в
процессе сборки страницы будет применено пустое значение, то будет
вставлено значение, указанное после параметра «empty»: <imgsrc=”path
to image” alt=”” />;
 /*{next|empty:<img src=”path to image” alt=”” />}*/ - параметр для
вставки шаблона кнопки «дальше».
Пример шаблона кнопки «домой» приведён на Листинге 11.
Листинг 11.
<a href="/*{href}*/" >
<img src="../homeImage.gif" alt="Return to home page" />
</a>
36
В данном шаблоне указан только один параметр:
/*{href}*/ − ссылка на страницу, которая расположена выше по иерархии
(родительская страница).
Пример шаблона кнопки «дальше» приведён на Листинге 12.
Листинг 12.
<a href="/*{href}*/" >
<img src="../nextPageImage.gif" alt="Go to next page" />
</a>
Опишем параметры данного шаблона:
/*{href}*/ − параметр для вставки ссылки на следующую страницу.
Пример шаблона пути навигации приведён на Листинге 13.
Листинг 13.
<a href='/*{href}*/'>/*{name}*/</a>/*{delimiter}*/
Опишем параметры данного шаблона:
1) /*{href}*/ - ссылка на текущую страницу;
2) /*{name}*/ - название страницы;
3) /*{delimiter}*/ - разделитель.
Пример шаблона для кнопки «назад» приведён на Листинге 14.
Листинг 14.
<a href="/*{href}*/" >
<img src="../PreviousImage.gif" alt="Previous page" />
</a>
37
Опишем параметры данного шаблона:
/*{href}*/ - ссылка на предыдущую страницу.
Для применения шаблонов к странице используются следующие
стратегии:
1) PageBuilderStrategy –
стратегия, которая отвечает за шаблон
страницы в целом. Схема класса представлена на рисунке 20.
РИС 16
 NavigationBarBuilderStrategy – стратегия, которая отвечает за
шаблон навигации (добавляет навигацию к странице).
представлена на рисунке 21.
38
Схема класса
РИС 17
 PathBuilderStrategy − применяет «шаблон пути навигации» к
входной странице документации. Схема класса представлена на рисунке 21.
РИС 18
Каждая из этих стратегий реализует интерфейс IHtmlModifierStrategy,
поэтому, чтобы пользователю задать свою собственную логику обработки
шаблона достаточно реализовать этот интерфейс и указать его в
конфигурационном файле [1].
39
3.4 Модуль модификации оглавления документации
Данный модуль предоставляет функции модификации оглавления
документации. Перечислим основные возможности модуля:
1. Фильтрация оглавления документации. Под фильтрацией понимается
удаление заголовков из оглавления документации. За данную функцию
отвечают следующие классы:
 IncludeTopicFilter. Для применения этого фильтра необходимо указать
заголовки, которые будут включены в оглавление, остальные заголовки
будут удалены. Схема данного класса представлена на рисунке 23.
РИС 19
 RemoveTopicFilter. Для применения этого фильтра необходимо указать
заголовки, которые будут исключены из оглавления. Схема данного
класса представлена на рисунке 24.
40
РИС 20
Общая схема взаимодействия рассмотренных классов представлена на
рисунке 25.
РИС 21
2. Удаление и замена слов из заголовков оглавления документации.
За данную функциональность отвечают следующие классы:

NumberRemoveFilter. Этот фильтр позволяет удалить нумерацию
из заголовков оглавления. Схема класса представлена на рисунке 26.
41
РИС 22
 ReplaceTopicByRegexFilter.
Позволяет
заменить
слова
в
заголовках по регулярным выражениям. Схема класса представлена на
рисунке 27.
РИС 23
42
3.5 Модуль конвертирования источника во внутреннее представление
На входе может быть несколько видов представления индексного
файла так и файла оглавления, поэтому при фильтрации и модификации
удобнее иметь дело с внутренним представлением этих файлов. Для таких
целей реализованы следующие классы:
 HhcToTreeNodeConverter;
 HhkToTreeNodeConverter;
 HtmlConverter;
 HtmlToChmConverter.
 IChmExtracter;
 TreeNode.
Структура класса HhcToTreeNodeConverter представлена на рисунке 28.
РИС 24
Этот класс конвертирует входной файл формата HHC во внутреннее
представление. В данном случае файл имеет структуру, которая некорректно
воспринимается
используются
парсером.
специальные
Чтобы
модификаторы
43
исправить
оглавления.
файл
После
их
применения, файл оглавления конвертируется во внутреннее представление
с использованием конвертора HhcToTreeNodeConverter.
Рассмотрим
класс
HhkToTreeNodeConverter,
структура
которого
представлена на рисунке 29.
РИС 25
Данный класс конвертирует входной файл формата HHK во внутреннее
представление.
Структура класса HtmlConverter представлена на рисунке 30.
44
РИС 26
Класс HtmlConverter конвертирует входной файл формата HTML во
внутреннее представление.
Все
перечисленные
HTML-страницы,
выше
чтобы
классы
упростить
работают
работу
с
с
DOM-моделью
DOM-моделью
была
использована библиотека HAP.
Рассмотрим
интерфейс
IChmExtracter.
представлена на рисунке 31.
45
Структура
интерфейса
РИС 27
Реализацией этого интерфейса является класс CompoundStorage.
Структура класса представлена на рисунке 32.
РИС 28
Данный класс предоставляет возможность декомпиляции (распаковки)
CHM-файла. CHM представляет собой тип документ, который сохраняется в
Compound File Binary Format (CFBF). CFBF является форматом хранения
данных,
первоначально
разработанный
Microsoft
и
открытый
для
использования. Класс CompoundStorage реализует возможность распаковки
файла сохранённого в CFBF формате. После распаковки CHM-файла мы
получаем набор HTML-страниц.
46
ЗАКЛЮЧЕНИЕ
В
результате
данной
работы
разработан
модуль
модификации
документации форматов HTML и CHM с возможностью конвертирования в
CHM формат.
Возможности модуля:
 Конвертирование CHM и HTML файлов в CHM формат.
 Импорт файлов форматов CHM, HTML.
 Форматирование документации с помощью HTML-шаблонов.
 Изменение содержания документации: замена и удаление строк по
регулярным выражениями, выражениям на языке XPATH.
 Изменение оглавления документации: удаление заголовков, изменение
названий заголовков и так далее.
 Импорт индексных файлов.
 Импорт файлов оглавления.
 Конфигурирование
процесса
конвертирования
и
модификации
был
использован
документации.
Спроектированы и реализованы соответствующие классы.
Для
работы
с
DOM-моделью
HTML-документов
HTML-парсер Html Agility Pack.
47
СПИСОК ЛИТЕРАТУРЫ
[1] Гамма Э., Хелм Р., Джонсон Р., Влиссидес Дж. Приемы объектноориентированного проектирования. Паттерны проектирования. // СПб:
Питер, 2001. — 368 с.
[2] Эндрю Троелсен. Язык программирования С# 2008 и платформа .NET 3.5
Framework // Вильямс: 2009 г. 1254 c.
[3] Алекс Макки. Введение в .NET 4.0 и Visual Studio 2010 для
профессионалов // Вильямс, 2010 г. 416 стр.
[4] 12.07.2005 Сергей Роговский Brightech Inc. Источник: RSDN Magazine #22005 // URL: http://www.rsdn.ru/article/java/spring.xml.
[5] Martin Fowler.//URL: http://martinfowler.com/articles/injection.html;
[6] Paul Hammant., Jan 25, 2006 // URL:
http://docs.codehaus.org/display/PICO/Inversion+of+Control.
[7] Wed, Nov 25 2009 6:41 PM, Matthew.Podwysocki. Going Interactive with the
Reactive Extensions. //URL:
http://codebetter.com/blogs/matthew.podwysocki/archive/2009/11/25/goinginteractive-with-the-reactive-extensions.aspx.
[8]
Unity
Application
Block
-
May
2008,
Microsoft
//
URL:
http://msdn.microsoft.com/en-us/library/ff650320.aspx.
[9] Fri, Oct 13 2006 8:37 PM by David Hayden
URL://http://codebetter.com/blogs/david.hayden/archive/2006/10/13/Inversion-ofControl-_2D00_-Dependency-Inversion-Principle-_2D00_-Castle_2700_sWindsor_2F00_MicroKernel.aspx.
48
[10] 37 Signals. Getting Real. // 2006, 37signals.
[11] Rework Jason Fried. RESOURCES About 37signals37signals products
ACKNOWLEDGMENTS // 2006, 37signals.
[12] J.D. Meier, Alex Homer, David Hill, Jason Taylor, Prashant Bansode, Lonnie
Wall, Rob Boucher Jr, Akshay Bogawat. Application Architecture.
Guide 2.0 // Microsoft Corporation, 2008.
49
ПРИЛОЖЕНИЕ
Пример конфигурации
Приведём пример конфигурации для разработанной библиотеки.
Модификация документации будет состоять из следующих шагов:
1. Смена представления страниц и навигационной панели:

Применение шаблона. Используемый шаблон приведен на
листинге 14.
Листинг 14
<html>
Dfd
<head>
<title>The SQL Language</title>
<meta name="generator" content="MySQL">
<meta name="keywords" content="">
/*{metaCharset}*/
/*{metaLanguage}*/
<link type="text/css" href="styles.css"
/*{links}*/
/*{styles}*/
<script
type="text/javascript"
src="nonscroll.js"></script>
/*{scripts}*/
</head>
rel="stylesheet"
/>
language="JavaScript"
<body>
<div id="hmpopupDiv"></div>
<div id="nsr">
<table cellspacing="0" cellpadding="0" id="Table1">
<tr valign="bottom">
<td align="left" rowspan="2" valign="center"></td>
<td align="left" valign="bottom">
<p
class='crumbs'>
<b>Navigation:</b> /*{navigationPath}*/
</p>
</td>
<td align="right" valign="middle" rowspan="2">
/*{navigationBar}*/
</td>
</tr>
<tr>
50
Приложение
Продолжение листинга 14
<td>
<p class="p_Heading1">
<span class="f_Heading1">
/*{pageHeader}*/
</span>
</p>
</td></tr>
</td>
<td align="right" valign="middle" rowspan="2">
/*{navigationBar}*/
</td>
</tr>
<tr>
<td>
<p class="p_Heading1">
<span class="f_Heading1">
/*{pageHeader}*/
</span>
</p>
</td>
</tr>
<tr>
<td colspan="3"></td>
</tr>
</table>
</div>
<div id="mainbody">
<div>
/*{pageContent}*/
<br>
</div>
</div>
</div>
</body>
</html>

Применение шаблонов для навигационных кнопок «далее»,
«назад», «домой». Шаблоны для этих кнопок приведены на листинге 15 и 16.
Листинг 15
<a href="/*{href}*/"
nmouseover="document.images.next.src='../Image1.gif'"
onmouseout="document.images.next.src='../Image2.gif'" >
<img name=next src="../BlurMetalDc3.gif" border=0 alt="Next page"></a>
51
Приложение
Листинг 16
<a href="/*{href}*/" onmouseover="document.images.prev.src='../ Image1.gif'"
onmouseout="document.images.prev.src='../Image2.gif'" >
<img name=prev src="../Image3.gif" border=0 alt="Previous page"></a>
<a href='/*{href}*/' onmouseover="document.images.main.src='../Image4.gif'"
onmouseout="document.images.main.src='../Image5.gif'">
<img name="main"
overview"></a>

src="../Image6.gif"
border="0"
alt="Return
to
chapter
Применение шаблона «навигационной панели». Этот шаблон
представлен на листинге 17:
Листинг 17
<table id="Table2">
<tr>
<td>
/*{previous|empty:<img src='../Image1.gif' border='0'>}*/
</td>
<td valign="top">
/*{home}*/
</td>
<td>
/*{next|empty:<img src='../Image2.gif' border='0'>}*/ </td>
<td>   </td>
</tr>
</table>
2. Удаление ссылок из содержание.
3. Удаление узлов из всех страниц документации, которые удовлетворяют
любому из выражений XPATH:
 //table[@name=’vasy’];
 //table[@name=’pety’].
4. Удалить нумерацию из оглавления.
5. Отфильтровать оглавление. Включить в результирующее содержание
только следующие заголовки:
52
Приложение
 Preface, Notes, Licenses;
 MySQL 5.4 Frequently Asked Questions;
 Errors, Error Codes, and Common Problems;
 MySQL Change History;
 Restrictions and Limits.
Описание проектного файла приведено на листинге 18.
Листинг 18
<?xml version="1.0" encoding="utf-8"?>
<ChmConfiguration
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<Sections>
<ProjectSection>
<Resources>
<string>.jpg</string>
<string>.png</string>
<string>.svg</string>
<string>.gif</string>
<string>.ico</string>
<string>.pdf</string>
<string>.css</string>
<string>.hhk</string>
<string>.js</string>
</Resources>
<AdditionalFiles>
<string>Templates\images</string>
</AdditionalFiles>
<SourceType>Chm</SourceType>
Продолжение
листинга 1
<OutputDirectoryPah>Output\mysql</OutputDirectoryPah>
<TempDirectoryPath>Temp\mysql</TempDirectoryPath>
<HhcPath>Hhc\hhc.exe</HhcPath>
<InputDirectories>
<string>Input\mysql\mysql.chm</string>
</InputDirectories>
<TemplatesSection>
<Templates>
<TemplateElement>
<Source>Templates\delimiterTemplate.html</Source>
<SourceType>Path</SourceType>
<Id>1</Id>
<Type>DelimiterTemplate</Type>
</TemplateElement>
<TemplateElement>
<Source>Templates\homeTemplate.html</Source>
<SourceType>Path</SourceType>
<Id>2</Id>
<Type>HomeTemplate</Type>
</TemplateElement>
53
Приложение
Продолжение листинга 18
<TemplateElement>
<Source>Templates\navigationBarTemplate.html</Source>
<SourceType>Path</SourceType>
<Id>3</Id>
<Type>NavigationBarTemplate</Type>
</TemplateElement>
</InputDirectories>
<AfterFiltrateStrategies>
<ModifierStrategyElement Type="HtmlNodeRepairStrategy" />
<ModifierStrategyElement Type="HtmlNodeRemoveStrategy">
<InputParameters>
<StringList>
<StringValue>//table[@width='100%'
and
@border='0' and @cellpadding='0' and @cellspacing='0']
</StringValue>
<StringValue>//table[@width='100%'
and
@border='0' and @cellpadding='4' and @cellspacing='0']</StringValue>
</StringList>
</InputParameters>
</ModifierStrategyElement>
<ModifierStrategyElement Type="PageBuilderStrategy" />
<ModifierStrategyElement Type="NavigationBarBuildStrategy" />
<ModifierStrategyElement Type="PathBuilderStrategy" />
</AfterFiltrateStrategies>
</ModifiersSection>
<FiltersSection>
<TableOfContentsFilters>
<FilterElement Type="NumberRemoveFilter" />
<FilterElement Type="ReplaceTopicByRegexFilter" />
<FilterElement Type="IncludeTopicFilter">
<InputParameters>
<StringList>
<StringValue>Preface, Notes, Licenses</StringValue>
<StringValue>Standard Index</StringValue>
<StringValue>MySQL Cluster NDB 6.X/7.X</StringValue>
<StringValue>MySQL
5.1
Frequently
Asked
Questions</StringValue>
<StringValue>Errors,
Error
Codes,
and
Common
Problems</StringValue>
<StringValue>MySQL Change History</StringValue>
<StringValue>Restrictions and Limits</StringValue>
</StringList>
</InputParameters>
</FilterElement>
</TableOfContentsFilters>
</FiltersSection>
</ProjectSection>
</Sections>
</ChmConfiguration>
54