docbook

Почему DocBook?

Юлия — Fri, 29 Jun 2007 20:16:47 +0400

Это история о том, как автоматизировать подготовку технической документации.

Долгое время я искала наиболее подходящий (т.е. наиболее гибкий и удобный) инструмент для написания текстов различной тематики, начиная с рефератов и курсовых работ в школе и университете, статей и заканчивая технической документацией программного продукта - руководство пользователя (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

существует возможность сохранить текст в следующих форматах -

MS Word (.doc), различные версии;
веб-страница (.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 — для более объемных и строже оформленных документов (книг)
- title — название
- author — авторы
- keyword — ключевые слова
- copyright — авторские права
- revhistory — история изменений
- chapter — глава книги
- section — раздел книги или статьи (произвольного уровня)
- abstract — аннотация
- preface — вступительное слово
- appendix — приложение
- bibliography — список литературы
- index — предметный указатель
Главы и разделы обычно начинаются с названия title.
- note — примечание
- tip — подсказка, совет
- warning — предупреждение (обычно об опасности для человека)
- caution — предупреждение (обычно об опасности для оборудования)
- important — важное замечание
- itemizedlist — маркированный
- orderedlist — нумерованный
- variablelist — список переменных или определений
Пункт списка оформляется тэгом listitem, термин или переменная в variablelist — тэгом term.
- emphasis — смысловое ударение
- filename — имя файла
- command — компьютерная команда
- option — опция (ключ) команды
- replaceable — переменная часть (аргумент) команды
- userinput — текст, вводимый пользователем
- computeroutput — сообщение программы
- literal — кодовое слово
- quote — просто закавыченный текст внутри абзаца
- blockquote — цитата из одного или нескольких абзацев
- citetitle — название процитированного источника
- ulink — интернет-ссылки
- link — перекрестные ссылки внутри документа, текст ссылки подставляется автоматически
- xref — перекрестные ссылки внутри документа, текстом ссылки можно задавать произвольно
- olink — ссылки на другие документы в рамках единой базы данных ресурсов
- footnote — примечание к тексту
- callout — примечание к иллюстрации или листингу программы
- graphic — простой, но не гибкий
- mediaobject — более сложный, позволяет автору предоставлять несколько альтернативных форматов изображения
- figure — иллюстрация, включаемая в автоматически генерируемый список иллюстраций
- informalfigure — иллюстрация без названия и не попадающая в список иллюстрация
- screenshot — графическая копия экрана компьютера
- inlinegraphic — упрощенный вариант
- inlinemediaobject — универсальный вариант
- table — таблица, включаемая в автоматически генерируемый список таблиц
- informaltable — таблица без названия и не включаемая список таблиц
- thead — шапка
- tbody — тело
- tfoot — подвал
- row — строка
- entry — ячейка
- entrytbl — вложенная таблица
- code — фрагмент программного кода внутри абзаца
- programlisting — текст программы
- screen — текст, видимый на экране компьютера
- literallayout — произвольный заранее отформатированный текст
- example — пример, включаемый в автоматически генерируемый список примеров
- informalexample — пример без названия и не попадающий в список примеров
- co — место, к которому относится примечание
- calloutlist — список примечаний, обычно следующий за листингом
- callout — текст примечания

В пятой версии DocBook теги sgmltag заменены на tag.

В данном примере различия определяются наличием и отсутствием одной небольшой CSS.

с подключением XML схем в Word - много проблем: далеко не каждая XML схема, даже соответствующая стандарту W3C XML shema, может быть использована в Word.

DocBook. Коротко.

Юлия — Fri, 29 Jun 2007 20:12:23 +0400

Что такое DocBook

DocBook - система подготовки технической документации. Точнее DocBook представляет собой XML формат, предназначенный для создания структурированных документов, в том числе книг, статей, технической документации. Особенно подходит для написания текстов компьютерной тематики.

DocBook поддерживается и стандартизируется DocBook Technical Committee (OASIS).

Описание DocBook первоначально существует в формате SGML и XML DTD, есть также и в других вариантах описания XML, в частности W3C XML Shema.

Командой разработчиков DocBook Open Repository и Norman Walsh разработан набор DSSSL и XSL stylesheets для генерации различных выходных форматов по DocBook документам: HTML, PDF, RTF, man pages, HTML Help.

Мы под DocBook будем понимать не только как таковой XML формат DocBook, но инструментарий DocBook XSL.

Пример кода

<book id="simple_book">
<title>Very simple book</title>

<chapter id="simplechapter">
<title>Chapter 1</title>
<para>Hello world!</para>
</chapter>
</book>

Подробнее

Текущая версия:

Официальный сайт DocBook: DocBook.org

Официальный сайт DocBook XSL:

Основная официальная документация: книга Norman Walsh "DocBook: The Definitive Guide".

Первоначально DocBook использовался в основном Open Source сообществом: в том числе the Linux Documentation Project, the GNOME и GTK+ API справочник, документация ядра Linux. В последнее время все больше организаций используют систему DocBook для всей программной документации, в том числе и для документирования коммерческих продуктов.

Возможности DocBook

Формат DocBook условно делится на Book и Article по функциональному назначению. Book используется для подготовки большой технической документации, книг и т.д., тогда как вид Article удобно использовать для статей.

Заготовка для Article DocBook Автоматически сгененрированная Altova XML Spy *

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<?xmlspysps http://www.altova.com/sps/Template/Publishing/docbook.sps?>
<article>
<title>Article Title</title>
<sect1>

<title>Section1 Title</title>
<para>Text</para>
</sect1>
</article>

Заготовка для Book DocBook

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<?xmlspysps http://www.altova.com/sps/Template/Publishing/docbook.sps?>
<book>
<bookinfo>
<title>Book Title</title>
<author>
<firstname>Author First Name</firstname>

<surname>Author Last Name</surname>
</author>
<publisher>
<publishername>Publisher Name</publishername>
</publisher>
<isbn>ISBN#</isbn>

<copyright>
<year>Copyright Year</year>
</copyright>
</bookinfo>
<part>
<title>Part Title</title>
<chapter>

<title>Chapter Title</title>
<sect1>
<title>Section1 Title</title>
<para>Text</para>
</sect1>
</chapter>

</part>
</book>

Существуют специализированные XML-редакторы, и большинство из них умеет работать с DocBook. Теоретически они предоставляют больший сервис по сравнению с обычными текстовыми редакторами: например, автоматически проверяют правильность вводимых тэгов, предлагают выбор тэгов в зависимости от контекста.
Благодаря открытому проекту DocBook XSLs, представляющему собой набор прекрасно настраиваемых DSSSL и XSL stylesheets, и существованию ряда как бесплатных, так и коммерческих инструментов для преобразования XML, вы легко (одной кнопкой) получаете свою документацию в различных форматах, в том числе и подготовленной для печати (в формате PDF).

Norman Walsh разработал модель публикации DocBook.
Внешний вид выходных форматов (HTML, CHM, PDF) легко настраивается с помощью CSS, а также через специальную XSL - Driver XSL.
DocBook определяет большое количество тегов, что может быть не очень удобно, но так как это XML формат, можно его упростить. Существует также модификация DocBook - Simple DocBook (упрощенный вариант)
Возможность модульной подготовки документации. Конечный выходнной файл легко собирается из нескольких отдельных XML файлов. Также возможна вставка текстов, листингов программ и всего чего захотите из внеших файлов. DocBook удобно использовать совместно с любой системой контроля версий.
И наоборот, DocBook позволяет из одного исходного документа создавать выходные документы не только в разных выходных форматах , но и с разным содержимым.

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

Предопределенные возможности словаря DocBook:

Библиография (список литературы)
Перекрестные ссылки (как внутри документа, так и между документами)
Сноски, примечания ....
Словари (список терминов)
Графика (вставка различных изображений)
Индексы
Таблицы, списки
Набор тегов для описания программ и GUI.

Как создавать и редактировать DocBook

Основной инструмент редактирования DocBook - обычный текстовый редактор, например, замечательный UltraEdit, так как DocBook является подмножеством XML и представляет собой обыкновенный текстовый документ с разметкой, аналогично документу HTML.

Подойдет также любой XML редактор, например Altova XML Spy (коммерческий).

В редакторе создается DocBook текст, затем с помощью XSLT процессора получаем данный текст в выходном формате HTML, CHM... Для получения PDF используем еще и XSL-FO процессор.

Преимущества DocBook

Система DocBook:

встроенные возможности для работы с различным содржанием;
сопровождается системой DocBookStylesheets, позволяющей используя различные инструменты преобразовывать DocBook контент в различные выходные форматы - HTML pages, PDF files, Microsoft HTMLHelp, UNIX man pages, JavaHelp, TeX, Texinfo, и RTF;

существует набор инструментов (free), которые также позволяют конвертировать различные форматы (man pages, HTML documents, Javadoc, plain text, Texinfo files, and OpenOffice Writer documents) в DocBook
хорошо документирована (DocBookThe Definitive Guide и DocBookTutorials, к сожалению, не на русском языке)
широко внедрена и протестирована такими коммерческими организациями как Sun, Microsoft, Hewlett-Packard, Novell, SCO, Caldera, и Red Hat, open-source группами - the KDE и GNOME, FreeBSD, Debian, и Linux documentation projects и the Darwin Documentation Project (Apple).
полностью открытый (open-source) стандарт
прекрасно настраиваемая и расширяемая система

Автоматически сгененрированная Altova XML Spy