Требования к оформлению выходных документов в различных проектах различны, поэтому попытки выпустить исчерпывающий набор XSLT-стилей, обречен на неудачу. Создавать XSLT-стиле заново в каждом проекте тоже нельзя, потому что сроки и стоимость этой работы выйдут неприемлемыми. На практике обычно используют свободно распространяемый комплект стандартных стилей DocBook XSL [7]. Он поддерживает основные элементы макетов и целевые форматы, а также хорошо приспособлен к доработке для нужд конкретного проекта. Благодаря архитектуре XSLT адаптация стандартных стилей не требует модификации их кода. Новые правила, располагаются в отдельных файлах, дополняют или замещают стандартные. Выполнены доработки привязаны к конкретной копии стандартных стилей, следовательно: — Доработка не конфликтуют друг с другом, и ими легко обмениваться;
обновления версий DocBook XSL ограничена только их обратной совместимостью. DocBook успешно используется при разработке и поддержке технической документации, особенно когда речь идет об объемах в тысячи и десятки тысяч страниц. Технология позволяет решить ряд типичных задач, возникающих при разработке технической документации, таких как: — Разработка и оформление документации в соответствии с отраслевыми и государственными стандартам (ЕСКД, ЕСПД, КСАС) — Автоматизация процедур нормоконтроля документации;
документации в различных электронных форматах, предназначенных для печати и просмотра на экране монитора: PDF, HTML, HTML H elp, JavaHelp, UnixManPages; - Поддержка многопользовательских режимов подготовки документации. Технология DocBook прекрасно подходит предприятиям, чья продукция сопровождается технической документацией, подготовленной и оформленной в соответствии с требованиями ГОСТ 2, 19 и 34 серии (ЕСКД, ЕСПД, КСАС). Однако, даже такая развитая технология, как DocBook, требует некоторой доработки при конкретном ее применении. Подготовка специализированной программной документации Одной из подсистем которую можно рассмотреть для примера, есть подсистема «Быстрые отчеты» SQL, которая служить жить для выдачи данных о таблицах-справочниках системы на основании SQL запросов. Подсистема «Быстрые отчеты» SQL должна иметь полноценную программную документацию, которая включает разделы руководства пользователя и руководства программиста (см. рис.
1). В состав программной документации также входит экранная помощь пользователю отчетов. Подготовка программной документации для подсистемы «Быстрые отчеты» SQL имеет ряд важных особенностей: — SQL запросы могут достаточно часто меняться во время эксплуатации системы темы, вместе с этим также изменяется внешний вид отчетов, и, следовательно, должна меняться документация;
документация должна формироваться во всех указанных выше видахДля конечного пользователя, для программиста, экранная помощь;
для пользователя должна быть представлена в нескольких форматах — в формате набора HTML-страниц и фор мате PDF-файла;
документация в виде экранной помощи реализуется спо мощью специальной программной системы и поэтому исходная информация для нее имеет быть представлена в виде XMLфайлов специального формата;
эксплуатации системы могут появляться новые отчеты SQL и удаляться существующие. Рис. 1. Диаграмма использования документации подсистемы Все эти факторы приводят к тому, что система подготовки программной документации, а особенно — система сопровождения программной документации должны быть очень динамичными и должны позволять быструю подготовку различных форматов документации из одного источника. В качестве основной системы документирования, на основании проведенного анализа, выбранная система документирования DocBook (реализация для Windows). Для получения необходимой документации экранной помощи в виде XML-файла, структура которого определена внешней системой подготовки экранной помощи, необходимо разработать скрипт конвертации средствами XSLT (речь преобразования XMLдокументов). Схема подготовки документации для подсистемы «Быстрые отчеты» SQL будет иметь вид, изображенный на рис.
2. Однако, подготовка описаний в формате DocBook для большого числа отчетов будет весьма трудоемкой, по этому прощеготовить начальные описания по значительно упрощенному шаблону «XML в специальном формате» (для системы помощи). Модифицированная схема подготовки документации приведена на рис. 3. Такое изменение направления потока данных в рабочем процессе приведет к экономии многих часов работы операторов по подготовке исходных описаний отчетов. Рис. 2.
Схема подготовки документации (вариант 1) Такой процесс подготовки документации является эквивалентным хорошо известному в программировании процессукомпиляции и сборки большого программного продукта. Рис. 3. Схема подготовки документации (вариант 2) ЗАКЛЮЧЕНИЕXML-схема является, чрезвычайно мощным, стандартом представления документации. Но эта мощь влечет за собой сложность программного обеспечения, работающего со схемой. В процессе исследования рассмотрены различные системы документирования программного за непосредственно печенье и обоснован выбор технологии DocBook.
Приведенный пример доработкой готовой системы документирования в конкретном случае задача подготовки специализированной программной документации (системы выдачи программных отчетов) решен более экономичным образом чем с использованием иных программных продуктов.
Список литературы
1. Липаев В. В. Документирование и управление конфигурацией программных средств / В. В. Липаев. — М .: Синтег, 2008. — 220 с. 2.
Липаев В. В. Качество программных средств / В. В. Липаев. — М: Янус-К, 2012. 400 с.
3. Технология DocBook и принцип единого источника [Электронный ресурс]. Режим доступа к ресурса:
http://glossterm.org/index.php4. Белайчук А. Кратчайший путь к DocBook [Электронный ресурс]. Режим доступа к ресурсу:
http://docbook.ru/doc/sw/5. Технический писатель. Базовые компетенции специалиста [Электронный ресурс]. режим доступа к ресурсу:
http://philosoft.ru/twskills.zhtml6. Технология DITA. Обзор возможностей и основные преимущества [Электронный ресурс]. режим доступа к ресурсу:
http://www.philosoft.ru/dita-intro.zhtml7. Н.Уолш. DocBook: The Definitive Guide [Электронныйресурс]. Режим доступа к ресурсу:
http://www.docbook.org/tdg/en/html/docbook.html.
