Почему DocBook?
Использование Docbook вместо Word для создания документации.
Это история о том, как автоматизировать подготовку технической документации.
Долгое время я искала наиболее подходящий (т.е. наиболее гибкий и удобный) инструмент для написания текстов различной тематики, начиная с рефератов и курсовых работ в школе и университете, статей и заканчивая технической документацией программного продукта - руководство пользователя (help к программе) и руководство программиста.
В конце концов я пришла к выводу, что наиболее гибким инструментом, т.е. предоставляющим наибольшие возможности для решения многих задач является текстовый процессор, а именно MS Word, но и он полон серьезных недостатков. Рассмотрим подробнее, почему же все-таки MS Word абсолютно не подходит для подготовки таких текстов, как, например, техническая документация.
Начинаем писать текст
Когда нужно срочно написать какой-либо текст, мы меньше всего желаем тратить время на обдумывание форматирования нашего текста, а между тем это одна из основных задач - качественное форматирование текста. Текст должен легко читаться, чаще всего нужно сохранить определенный стиль форматирования (некий корпоративный стиль), и в конце концов внешний вид будущей статьи должен радовать глаз.
MS Word.
На первый взгляд Word предоставляет самые широкие возможности форматирования - пользуйся стилями и все в порядке. Но за кажущейся простотой применения стилей в Word, скрывается много сложностей и ошибок, подстерегающих неопытного пользователя и много головной боли для опытного пользователя.
Проблема первая - текст, который легко форматируется впоследствии
Если мы хотим менять оформление текста после его написания, в частности для того, чтобы подобрать наиболее симпатичные шрифты и интервалы, чтобы текст читался лучше, необходимо каждый элемент текста - будь то параграф, заголовок или имя файла внутри параграфа - еще на этапе написания текста выделить определенным стилем. Тогда в последствии изменив характеристики конкретного стиля, мы изменим внешний вид каждого элемента текста, к которому был применен этот стиль.
В Word
для этих целей существует панель форматирования, стили и шаблоны. Система стилей достаточна гибкая - набор применяемых в документе стилей может быть как расширен своими собственными стилями, так и уменьшен. Но для этих целей, если вы пишете техническую документацию не в последний раз - вам необходимо придумать собственный шаблон со стилями, которые будут включать такие элементы как, например, код (листинг программы), имя файла, стили для таких параграфов как warning, note и так далее.
В DocBook
здесь же вы просто открываете практически любой XML редактор (как впрочем можно и простой текстовый редактор, но с ним будет по сложнее), и совершенно не задумываясь о стилях и форматировании набираете текст в формате XML, используя теги формата DocBook. Эти теги однозначно определяют назначение каждого элемента текста.
<para>На собственном опыте проверено, что DocBook имеет <emphasis>все</emphasis> необходимое - чтобы правильно структурировать текст как большой, типа книги, так и маленький - как, например, эта статья.</para> <para>Названия тегов интуитивно понятны и не возникает двусмысленности, не надо задумываться какой тег выбрать. Если это заголовок, не вожно чего статьи или секции - это <sgmltag>title</sgmltag>, если это сноска - значить <sgmltag>footnote</sgmltag> - все очень-очень просто.</para> *
Набор тегов DocBook очень хорошо продуман (системе DocBook ведь уже 10 лет) - в нем существуют все необходимые элементы для оформления технической документации и структура формата DocBook такова, что вы с легкостью сможете структурировать свой текст по частям, разделив на секции разного уровня, параграфы различных типов, а также различные списки, библиографии, индексы и т.д.
На собственном опыте проверено, что DocBook имеет все необходимое - чтобы правильно структурировать текст как большой, типа книги, так и маленький - как, например, эта статья.
Названия тегов интуитивно понятны и не возникает двусмысленности, не надо задумываться какой тег выбрать. Если это заголовок, не важно чего статьи или секции - это title, если это сноска - значить footnote - все очень-очень просто.
Наглядность набираемого текста обеспечивается подсветкой тегов существующей в XML редакторах, а также в некоторых XML редакторах предусмотрены специальные WISYWIG режимы, в которых вы как и в Word'e видете и редактируете сразу отформатированный текст:
Еще одно преимущество XML формата и XML редактора - вы никак не ошибетесь с форматированием - редактор всегда подскажет и укажет, как тег в данном контексте уместен, а какой просто не возможен. Таким образом на выходе вы всегда получаете "чистую" разметку.
Проблема вторая - изменение внешнего вида
В Word
Если все стили были в тексте применены правильно, то изменить, например, внешний вид заголовков второго уровня не составит труда - вы просто изменяете формат стиля используемого для заголовков второго уровня, при этом должен поменяться вид всех таких заголовков
Ну а если мы желаем применить какой то особенный стиль всего текста, например, наш собственный корпоративный стиль? Меняем стиль каждого элемента поотдельности или пытаемся применить свой шаблон документа, в котором кстати имена стилей одинаковых по смыслу элементов могут и не соответствовать; к тому же, к слову сказать, применение другого шаблона к уже написанному тексту не совсем тривиальная задача в Word'е. Далее, на следующей неделе мы поменяли свой корпоративный стиль (может даже и не сильно), что делать с уже написанным текстом? опять менять шаблон.
В DocBook
Еще раз повторюсь - вы пишете текст в формате DocBook и не забываете его структурировать в соответствии со смысловой нагрузкой каждого элемента, а о последующем форматировании (внешнем виде выходного документа) вы не думаете вовсе.
Благодаря открытому проекту DocBook XSLs, представляющему собой набор прекрасно настраиваемых DSSSL и XSL stylesheets, и использованию CSS, вы или кто-то другой легко сможете настроить внешний вид выходного документа, в любой момент его можно изменить и применить уже готовые использованные ранее шаблоны.
При написании текста в стиле DocBook вы храните отдельно мухи (данные) и котлеты (шаблоны форматирования), что позволяет легко и быстро менять внешний вид выходного документа, не изменяя сам файл, содержащий текст, а также дает дополнительную возможность - легкий доступ к данным внутри документа.
Ниже приведена классификация тегов DocBook (автор А. Белайчук). Это не полная классификация, но в ней приведены большинство наиболее употребительных тегов (см. там).
Сохраняем, публикуем и печатаем текст
Проблема третья - хранение исходного текста документа
Хранение документа в формате Word
с немалыми затратами дискового пространства. В этом формате хранятся как данные, так и форматирование этого документа, причем в файле Word кроме необходимого форматирования, которое обеспечивает внешний вид нашего документа, сохраняется также много "лишних" данных.
Таким образом, сохраняя в Word несколько документов одинакового форматирования, информация о форматах дублируется во всех файлах.
В DocBook
как уже было сказано выше - информация храниться отдельно от дизайна и соответственно не повторяется.
Проблема четвертая - сохранение в различных форматах.
В Word 2003
существует возможность сохранить текст в следующих форматах -
веб-страница (.html), несколько вариантов;
RTF;
обычный текст;
XML документ (WordML или свой формат XML - надо только подключить XML схему *).
Все эти форматы плохо передают форматирование, сделанное в Word; и к тому же добавляют много совершенно ненужной информации.
В DocBook
Благодаря открытому проекту DocBook XSLs, представляющему собой набор прекрасно настраиваемых DSSSL и XSL stylesheets, и существованию ряда как бесплатных, так и коммерческих инструментов для преобразования XML, вы легко (одной кнопкой) получаете свою документацию в различных форматах, в том числе и подготовленной для печати (в формате PDF).
- Форматы поддерживаемые DocBook XSLs:
-
HTML, XHTML (один выходной файл или несколько с навигацией для переходов по страницам)
-
HTMLhelp (CHM)
-
XSL-FO (затем в PDF)
-
javahelp
-
manpages
-
slides (создание слайдов, выходной формат - любой из выше перечисленных)
-
WordML
Используем текст повторно
Включаем в текст внешние данные
Классификация тегов DocBook
-
- Корневые теги
-
article — для документов относительно небольшого объема (формата статьи)
-
book — для более объемных и строже оформленных документов (книг)
Корневым называется самый внешний тег XML-документа. Корневыми тегами DocBook обычно служат:
-
-
- Сопроводительная информация
-
title — название
-
author — авторы
-
keyword — ключевые слова
-
copyright — авторские права
-
revhistory — история изменений
Документ DocBook обычно начинается тегом articleinfo или bookinfo, который группирует следующую информацию:
-
-
- Структура документа
-
chapter — глава книги
-
section — раздел книги или статьи (произвольного уровня)
-
abstract — аннотация
-
preface — вступительное слово
-
appendix — приложение
-
bibliography — список литературы
-
index — предметный указатель
Структурные теги делят документ на главы и разделы:
Главы и разделы обычно начинаются с названия title.
-
-
- Абзацы
-
note — примечание
-
tip — подсказка, совет
-
warning — предупреждение (обычно об опасности для человека)
-
caution — предупреждение (обычно об опасности для оборудования)
-
important — важное замечание
Регулярный текст в DocBook оформляется тегом para. Это — наиболее часто используемый тег.
Абзацы, требующие особого внимания, оформляются тегами:
-
-
- Списки и перечни
-
itemizedlist — маркированный
-
orderedlist — нумерованный
-
variablelist — список переменных или определений
Списки в DocBook бывают следующих видов:
Пункт списка оформляется тегом listitem, термин или переменная в variablelist — тегом term.
-
-
- Выделенный текст
-
emphasis — смысловое ударение
-
filename — имя файла
-
command — компьютерная команда
-
option — опция (ключ) команды
-
replaceable — переменная часть (аргумент) команды
- userinput — текст, вводимый пользователем
-
computeroutput — сообщение программы
-
literal — кодовое слово
Теги для выделения текста внутри абзаца:
-
-
- Цитаты
-
quote — просто закавыченный текст внутри абзаца
-
blockquote — цитата из одного или нескольких абзацев
-
citetitle — название процитированного источника
Теги для цитат:
-
-
- Ссылки
-
ulink — интернет-ссылки
-
link — перекрестные ссылки внутри документа, текст ссылки подставляется автоматически
-
xref — перекрестные ссылки внутри документа, текстом ссылки можно задавать произвольно
-
olink — ссылки на другие документы в рамках единой базы данных ресурсов
Теги для различных вариантов ссылок:
-
footnote — примечание к тексту
-
callout — примечание к иллюстрации или листингу программы
К разновидности ссылок можно отнести также сноски:
-
-
- Иллюстрации
-
graphic — простой, но не гибкий
-
mediaobject — более сложный, позволяет автору предоставлять несколько альтернативных форматов изображения
Для вставки в текст изображений в DocBook есть два способа:
-
figure — иллюстрация, включаемая в автоматически генерируемый список иллюстраций
-
informalfigure — иллюстрация без названия и не попадающая в список иллюстрация
-
screenshot — графическая копия экрана компьютера
Графику можно вставлять непосредственно внутрь раздела или абзаца, но предпочтельнее — в один из следующих тегов:
-
inlinegraphic — упрощенный вариант
-
inlinemediaobject — универсальный вариант
Там, где требуется, чтобы текст обтекал изображение, используются теги:
-
-
- Таблицы
-
table — таблица, включаемая в автоматически генерируемый список таблиц
-
informaltable — таблица без названия и не включаемая список таблиц
Корневые теги таблицы DocBook:
-
thead — шапка
-
tbody — тело
-
tfoot — подвал
-
row — строка
-
entry — ячейка
-
entrytbl — вложенная таблица
Содержимое таблицы:
-
-
- Компьютерные листинги
-
code — фрагмент программного кода внутри абзаца
-
programlisting — текст программы
-
screen — текст, видимый на экране компьютера
-
literallayout — произвольный заранее отформатированный текст
Теги для различных вариантов компьютерных листингов, форматируемых "как есть" :
-
example — пример, включаемый в автоматически генерируемый список примеров
-
informalexample — пример без названия и не попадающий в список примеров
Листинги можно вставлять непосредственно в раздел или абзац, но часто они являются содержимым следующих тегов:
-
co — место, к которому относится примечание
-
calloutlist — список примечаний, обычно следующий за листингом
-
callout — текст примечания
Листинги часто сопровождаются примечаниями-сносками:
-
Почему то вы не упомянули процесс инсталляции и настройки продуктов. Если MS Word устанавливается в автоматическом режиме, пользователю надо только следовать мастеру установки. С DocBook же ситуация достаточно запутанная, надо установить несколько продуктов от разных производителей. Более того, пока я нигде в интернете не смог найти пошагового описания настройки DocBook под WindowsXP.
Т.е. время вхождения в этот проект гораздо выше, чем для MS Word.
Для того, чтобы использовать Docbook надо иметь потребность, а не просто желание. Тогда выгоды, предоставляемые Docbook, перекроют все затраты на его внедрение (и временные и финансовые).
P.S. Под XP все просто настраивается.
Спасибо автору, материал просто замечательный
Жалко, что я сначала разобрался методом тыка и чтения манов, прежде чем нашёл Вашу заметку
Отныне с собираюсь везде и повсеместно в своих проектах примерять DocBook
а MSO я не применяю уже года два, вместо него использую ООо
Интересно ООо умеет работать с DocBook ?
OOo умеет работать с DocBook - очень коротко можно посмотреть тут
http://xml.openoffice.org/xmerge/docbook/UserGuide.html
Но не советую использовать OOo для docbook - неудобно.
Лучше использовать Xml редакторы.
Если Вы технический писатель и работаете с большими текстами,
Вам подойдет Serna.
Если Вы разработчик, то Вам подойдет
Oxygen или AltovaXMLspy
Oxygen вроде кучу денег стоит
я по старинке, в любом текстовом редакторе
А не опишите подробнее про установку необходимых программ под Windows?
Самая основная проблема, с которой столкнулся, это вывод русских букв в PDF.
Описать установку и настройку - это трудно. Я несколько раз переустанавливал и каждый раз "парился". Легче выложить уже настроенный пакет и пример документа с командными файлами (например, bat) для преобразований. Про "прекрасно настраиваемые DSSSL и XSL stylesheets" - это тоже смело сказано. А в остальном согласен MSO как и OOo не средства для создания тех.документации, а особенно если над документом работает несколько человек. DocBook + контроль версий рулят!
Вот это настроенный софт (libxml, docbook_xsl ):
http://files2.north.kz/f/ftp6101/docbook_bins.7z
Его надо куда-то разархивировать (например, D:\CPP\libxml) и прописать путь к каталогу D:\CPP\libxml\bin
Вот это демо проект
http://files2.north.kz/f/ftp6101/DevGuide.7z
В xsl\html.xsl и xsl\pdf_xer.xsl надо поменять пути к D:\CPP\libxml
Ах да! Забыл еще один важный весч! Хе-хе!
Правда совсем не хе-хе, а ХЕР. Для преобразования в PDF. Правда ХЕР ставит снизу на странице свой лэйбл, но при печати не видно и с русским работает ОК. Можете экспериментировать с другими пакетами. Терпенье и труд все перетрут :)
Здесь же все уже настроено (например, шрифты).
Опять же пропишите путь к x4u.bat и xep.bat. Ну и в них загляните. Там надо тоже пути подправить.
Итак рецепт "слезы комсомолки":
http://files2.north.kz/f/ftp6101/xep.7z
Если что не пойдет, то может быть даже отвече на мэйлы :)
Не работают ссылки, а жаль.
Обратите внимание что в примере все настроено для "xi:include".
"Сборка" из частей была одним из основных условий. Тоже сразу не работало. Видимо руки кривые или ошибка в ДНК. Гы-гы-гы!!!
Инструкции
Не могли бы вы еще раз перезалить 3 сборочки, плиз?
Нстроенный софт, демо проект и XEP.
Заранее спасибо.
Могу,
только уточните, плиз,
под windows?
libxml или xalan?
Да, было бы здорово увидеть под Windows с Xalan
Было-бы не плохо под windows с libxml
Печально на самом деле... Я почему-то думал, что DocBook - нормальный формат, который можно хранить под контролем версий (и над документом сможет работать несколько человек, при необходимости сливая изменения), а оказывается - такая же гадость, как вордовские документы (нет нормального 3-way merge и т.п.).
Спасибо, развеяли мои заблуждения... пошёл дальше копать в сторону wiki-подобных markup languages.
А почему нельзя делать 3 way merge, это же обычный XML? Объясните, пожалуйста.
Post new comment