Введение
Язык разметки для документации
DocBook — это семантический язык разметки для технической документации. Изначально он был разработан для создания технической документации по компьютерному оборудованию и программному обеспечению, но может использоваться для любого типа документации. Как семантический язык, DocBook позволяет пользователям создавать содержание документа в представлении, независимом от формата, сохраняя при этом его логическую структуру. Это содержание затем можно опубликовать в различных форматах, таких как HTML, XHTML, EPUB, PDF, man pages, WebHelp и HTML Help, без необходимости вносить какие-либо изменения в исходный текст. Иными словами, документ, написанный в формате DocBook, легко переносится в другие форматы, вместо того чтобы требовать переписывания.
Схемы и валидация
Правила формально определены в XML-схеме DocBook. Соответствующие инструменты разработки могут проверять XML-документ (DocBook или любой другой) на соответствие его схеме, чтобы определить, нарушает ли документ правила этой схемы и где именно это происходит. Инструменты редактирования XML также могут использовать информацию о схеме, чтобы предотвратить создание некорректных документов.
Авторство и обработка
Поскольку DocBook основан на XML, документы могут быть созданы и отредактированы в любом текстовом редакторе. Специализированный XML-редактор также является функциональным редактором DocBook. DocBook предоставляет файлы схем для популярных языков схем XML, поэтому любой XML-редактор, поддерживающий автодополнение на основе схемы, может делать это и для DocBook. Многие графические или WYSIWYG XML-редакторы позволяют редактировать DocBook как текстовый процессор. Таблицы, элементы списков и другой стилизованный контент можно копировать и вставлять в редактор DocBook, и он будет сохранен в выходном XML-файле DocBook. DocBook доступен как в формате SGML, так и в формате XML, в виде DTD. Существуют версии XML-схемы RELAX NG и W3C XML Schema. Начиная с DocBook 5, версия RELAX NG является "нормативной", и из нее генерируются другие форматы. Изначально DocBook был разработан как SGML-приложение, но затем было создано эквивалентное XML-приложение, которое сейчас заменило SGML-приложение для большинства задач. (Начиная с версии 4 DTD SGML, схема нумерации версий была продолжена в XML DTD.) Первоначально DocBook использовался ключевой группой компаний-разработчиков программного обеспечения, чьи представители участвовали в его первоначальном проектировании. Однако со временем DocBook был принят сообществом открытого исходного кода, где он стал стандартом для создания документации для многих проектов, включая FreeBSD, KDE, документацию рабочего стола GNOME, справочные материалы по API GTK+, документацию ядра Linux (которая, по состоянию на июль 2016 года, переходит на Sphinx/reStructuredText) и разработки Linux Documentation Project.
Пре-Докбук версия 5.0
До версии DocBook 5, DocBook определялся нормативно с помощью определения типа документа (DTD). Поскольку DocBook изначально создавался как приложение SGML, DTD был единственным доступным языком схем. Форматы DocBook 4.x могут быть SGML или XML, но XML-версия не имеет собственного пространства имен. Форматы DocBook 4.x должны были соответствовать ограничениям, налагаемым DTD. Наиболее существенным ограничением было то, что имя элемента однозначно определяет его возможное содержимое. То есть, элемент с именем info должен содержать одну и ту же информацию, независимо от его расположения в файле DocBook. Поэтому в DocBook 4.x существует множество элементов info: bookinfo, chapterinfo и т.д. У каждого из них немного отличается модель содержимого, но они разделяют некоторые общие элементы модели содержимого. Кроме того, они дублируют контекстную информацию. Элемент info книги является таковым, поскольку он является прямым потомком элемента book и не требует специального наименования для читателя. Однако, поскольку формат определялся DTD, он должен был быть назван именно так. Корневой элемент не имеет и не нуждается в версии, поскольку версия встроена в объявление DTD в начале документа DocBook до версии 5. Документы DocBook 4.x несовместимы с DocBook 5, но могут быть преобразованы в документы DocBook 5 с помощью таблицы стилей XSLT. Одна из таких таблиц (db4upgrade.xsl) поставляется в составе пакета схемы и спецификаций DocBook 5.
Форматы вывода
Файлы DocBook используются для подготовки выходных файлов в самых разных форматах. Почти всегда это достигается с помощью таблиц стилей DocBook XSL. Это XSLT-стили, которые преобразуют документы DocBook в различные форматы (HTML, XSL FO для последующего преобразования в PDF и т. д.). Эти таблицы стилей могут быть достаточно сложными, чтобы генерировать оглавления, глоссарии и указатели. Они могут управлять выбором определенных выделенных фрагментов основного документа для создания различных версий одного и того же документа (например, "учебника" или "краткого руководства", каждый из которых состоит из подмножества материала). Пользователи могут создавать собственные стили или даже полноценную программу для обработки DocBook и преобразования его в нужный выходной формат в соответствии со своими потребностями. Норман Уолш и команда разработчиков проекта DocBook поддерживают основное приложение для создания выходных данных из исходных документов DocBook: набор XSLT-стилей (а также устаревший набор DSSSL-стилей), который может генерировать высококачественный HTML и печатные материалы (FO/PDF), а также выходные данные в других форматах, включая RTF, страницы man и HTML Help. Веб-справка также является примером веб-справки и входит в состав дистрибутива DocBook XSL. Основные особенности: макет страницы, полностью основанный на CSS, поиск по содержимому справки и оглавление в виде сворачиваемого дерева. Поиск включает стемминг, выделение совпадений, явную оценку страниц и стандартный многоязычный токенизатор. Поиск и оглавление расположены в панели, которая отображается как фреймсет, но фактически реализована с использованием тегов div и cookie (что обеспечивает ее прогрессивную загрузку).
Упрощенная DocBook
DocBook предлагает множество функций, которые могут показаться сложными для начинающего пользователя. Для тех, кто ценит удобство DocBook, но не хочет тратить много времени на его освоение, был разработан Simplified DocBook. Это небольшое подмножество DocBook, предназначенное для отдельных документов, таких как статьи или технические обзоры (то есть поддержка "книг" не предусмотрена). Текущая версия DTD Simplified DocBook – 1.1.
Критика
Инго Шварце, автор mandoc в OpenBSD, считает DocBook уступающим семантическому макросу mdoc для страниц руководства. Пытаясь создать конвертер из DocBook в mdoc (предыдущие конвертеры, такие как docbook to man, не поддерживают семантические элементы), он обнаружил, что семантические части одновременно "раздуты, избыточны и неполны" по сравнению с элементами, охватываемыми mdoc. Более того, Шварце считает спецификацию DocBook недостаточно конкретной в отношении использования тегов, язык – непереносимым между версиями, детализированным небрежно и в целом непоследовательным.