DocBook — язык семантической разметки технической документации . Первоначально он предназначался для написания технической документации, связанной с компьютерным оборудованием и программным обеспечением, но его можно использовать для любого другого вида документации. [1]
Как семантический язык, DocBook позволяет пользователям создавать содержимое документа в нейтральной к представлению форме , которая отражает логическую структуру содержимого; этот контент затем может быть опубликован в различных форматах, включая HTML , XHTML , EPUB , PDF , man-страницы , WebHelp [2] и HTML-справку , не требуя от пользователей внесения каких-либо изменений в исходный код. Другими словами, когда документ написан в формате DocBook, его можно легко переносить в другие форматы, и его не нужно переписывать.
DocBook — это язык XML . В текущей версии (5.x) язык DocBook формально определяется схемой RELAX NG со встроенными правилами Schematron . (Существуют также версии схемы W3C XML Schema +Schematron и Document Type Definition (DTD), но они считаются нестандартными.)
Как семантический язык, документы DocBook описывают не то, как «выглядит» их содержимое, а скорее значение этого содержимого. Например, вместо того, чтобы объяснять, как можно визуально отформатировать аннотацию статьи, DocBook просто говорит, что конкретный раздел является аннотацией. Внешний инструмент обработки или приложение должны решить, где на странице должна располагаться аннотация и как она должна выглядеть, и следует ли вообще включать ее в окончательный результат.
DocBook предоставляет огромное количество тегов семантических элементов. Они разделены на три широкие категории: структурные, блочные и встроенные.
Структурные теги определяют общие характеристики своего содержимого. Например, элемент bookуказывает, что его дочерние элементы представляют части книги. Сюда входят название, главы, глоссарии, приложения и т. д. Структурные теги DocBook включают, помимо прочего:
set: Озаглавленная коллекция из одного или нескольких books или articles, может быть вложена в другие наборы.book: Озаглавленный сборник chapters, articles и/или parts с дополнительными глоссариями, приложениями и т. д.part: Озаглавленная коллекция из одного или нескольких chapters — может быть вложена в другие части и может иметь специальный вводный текст.article: Озаглавленная ненумерованная коллекция элементов уровня блока.chapter: озаглавленная, пронумерованная коллекция элементов уровня блока — главы не требуют явных номеров, номер главы — это количество элементов предыдущей главы в XML-документе плюс 1.appendix: Содержит текст, представляющий приложение.dedication: Текст представляет собой обозначение содержащегося структурного элемента.Структурные элементы могут содержать другие структурные элементы. Структурные элементы — единственные разрешенные элементы верхнего уровня в документе DocBook.
Теги уровня блока — это такие элементы, как абзацы, списки и т. д. Не все эти элементы могут напрямую содержать текст. Последовательные элементы уровня блока визуализируются один «после» другого. After в данном случае может отличаться в зависимости от языка. В большинстве западных языков «после» означает «ниже»: абзацы текста печатаются вниз по странице. Системы письма других языков могут иметь разную направленность ; например, в японском языке абзацы часто печатаются нисходящими столбцами, причем столбцы идут справа налево, поэтому «после» в этом случае будет слева. Семантика DocBook совершенно нейтральна по отношению к такого рода языковым концепциям.
Теги строкового уровня — это такие элементы, как выделение, гиперссылки и т. д. Они оборачивают текст внутри элемента уровня блока. Эти элементы не приводят к разрыву текста при отображении в формате абзаца, но обычно они заставляют процессор документов применять определенную типографскую обработку к заключенному в нем тексту путем изменения шрифта, размера или подобных атрибутов. (В спецификации DocBook говорится , что ожидается различная типографская обработка, но она не предлагает конкретных требований относительно того, какой может быть эта обработка.) То есть процессору DocBook не нужно преобразовывать тег emphasisв курсив . Процессор DocBook на основе чтения может увеличить размер слов, а текстовый процессор может использовать жирный шрифт вместо курсива.
<?xml version="1.0"coding="UTF-8"?> <book xml:id= "simple_book" xmlns= "http://docbook.org/ns/docbook" version= "5.0" > <title> Очень простая книга </title> <chapter xml:id= "chapter_1" > <title> Глава 1 </title> <para> Привет, мир! </para> <para> Надеюсь , что ваш день проходит <emphasis> великолепно </emphasis> ! </para> </chapter> <chapter xml:id= "chapter_2" > <title> Глава 2 </title> <para> И снова здравствуй , мир! </para> </глава> </book> Семантически этот документ представляет собой «книгу» с «названием», содержащую две «главы», каждая со своими «названиями». Эти «главы» содержат «абзацы», содержащие текст. Разметка на английском языке вполне читаема.
Более подробно, корневым элементом документа является book. Все элементы DocBook находятся в пространстве имен XML , поэтому корневой элемент имеет атрибут xmlns для установки текущего пространства имен. Кроме того, корневой элемент документа DocBook должен иметь версию , указывающую версию формата, на котором построен документ.
(Документы XML могут включать элементы из нескольких пространств имен одновременно, как idатрибуты в примере.)
Элемент bookдолжен содержать title, или infoэлемент, содержащий title. Это должно быть перед любыми дочерними структурными элементами. После заголовка идут структурные дочерние элементы, в данном случае два chapterэлемента. Каждый из них должен иметь файл title. Они содержат paraблочные элементы, которые могут содержать произвольный текст и другие встроенные элементы, например, emphasisво втором абзаце первой главы.
Правила формально определены в XML-схеме DocBook . Соответствующие инструменты программирования могут проверять XML-документ (DocBook или другой) на соответствие его соответствующей схеме, чтобы определить, не соответствует ли (и где) документ этой схеме. Инструменты редактирования XML также могут использовать информацию о схеме, чтобы избежать создания несоответствующих документов.
Поскольку DocBook представляет собой XML, документы можно создавать и редактировать в любом текстовом редакторе. Специальный редактор XML также является функциональным редактором DocBook. DocBook предоставляет файлы схем для популярных языков схем XML, поэтому любой редактор XML, который может обеспечить завершение содержимого на основе схемы, может сделать это для DocBook. Многие графические или WYSIWYG -редакторы XML имеют возможность редактировать DocBook как текстовый процессор . [3]
Таблицы, элементы списков и другой стилизованный контент можно скопировать и вставить в редактор DocBook, и они будут сохранены в выходном XML-файле DocBook. [3] Поскольку DocBook соответствует четко определенной схеме XML, документы можно проверять и обрабатывать с помощью любого инструмента или языка программирования, включающего поддержку XML.
DocBook зародился в 1991 году в дискуссионных группах Usenet и в конечном итоге стал совместным проектом HAL Computer Systems и O'Reilly & Associates и в конечном итоге породил собственную организацию по техническому обслуживанию (Davenport Group), а затем в 1998 году перешел в консорциум SGML Open , который впоследствии стал ОАЗИС . DocBook в настоящее время поддерживается Техническим комитетом DocBook в OASIS. [4]
DocBook доступен как в форме SGML , так и в форме XML , как DTD . Доступны формы RELAX NG и W3C XML Schema версии XML. Начиная с DocBook 5, версия RELAX NG является «нормативной» формой, на основе которой генерируются другие форматы.
DocBook изначально создавался как приложение SGML, но было разработано эквивалентное приложение XML, которое теперь заменило приложение SGML для большинства применений. (Начиная с версии 4 SGML DTD, XML DTD продолжал использовать эту схему нумерации версий.) Первоначально ключевая группа компаний-разработчиков программного обеспечения использовала DocBook, поскольку их представители участвовали в его первоначальной разработке. Однако со временем DocBook был принят сообществом открытого исходного кода, где он стал стандартом для создания документации для многих проектов, включая FreeBSD , KDE , документацию рабочего стола GNOME , ссылки на GTK+ API , документацию по ядру Linux (которая по состоянию на июль 2016 г. , происходит переход на Sphinx / reStructuredText [5] [6] ), а также работа Linux Documentation Project .
До DocBook 5 DocBook нормативно определялся определением типа документа (DTD). Поскольку DocBook изначально создавался как приложение SGML , DTD был единственным доступным языком схемы. Форматы DocBook 4.x могут быть SGML или XML, но версия XML не имеет собственного пространства имен.
Форматы DocBook 4.x должны были соответствовать ограничениям, определенным DTD. Самым существенным ограничением было то, что имя элемента однозначно определяло его возможное содержимое. То есть элемент с именем infoдолжен содержать одну и ту же информацию независимо от того, где он находится в файле DocBook. Таким образом, в DocBook 4.x существует множество видов информационных элементов: bookinfo, chapterinfoи т. д. Каждый из них имеет немного разную модель контента, но некоторые из них имеют общую модель контента. Кроме того, они повторяют контекстную информацию. Элемент книги infoв том, что она является прямым потомком книги; его не нужно называть специально для читателя-человека. Однако, поскольку формат был определен в DTD, его нужно было назвать таковым. Корневой элемент не имеет версии и не нуждается в ней, поскольку версия встроена в объявление DTD в верхней части документа до DocBook 5.
Документы DocBook 4.x несовместимы с DocBook 5, но могут быть преобразованы в документы DocBook 5 с помощью таблицы стилей XSLT. Один ( db4-upgrade.xsl) предоставляется как часть пакета схемы и спецификаций DocBook 5. [7]
Файлы DocBook используются для подготовки выходных файлов в самых разных форматах. Почти всегда это достигается с помощью таблиц стилей DocBook XSL . Это таблицы стилей XSLT , которые преобразуют документы DocBook в ряд форматов ( HTML , XSL-FO для последующего преобразования в PDF и т. д.). Эти таблицы стилей могут быть достаточно сложными для создания оглавлений, глоссариев и указателей. Они могут контролировать выбор определенных частей основного документа для создания различных версий одного и того же документа (например, «учебника» или «краткого справочного руководства», где каждая из них состоит из подмножества материала). Пользователи могут писать свои собственные таблицы стилей или даже полноценную программу для обработки DocBook в соответствующем выходном формате в соответствии с их потребностями.
Норман Уолш и команда разработчиков проекта DocBook поддерживают ключевое приложение для создания выходных данных из исходных документов DocBook: набор таблиц стилей XSLT (а также устаревший набор таблиц стилей DSSSL ), которые могут генерировать высококачественный HTML и печатать ( FO / PDF ). вывод, а также вывод в других форматах, включая RTF , справочные страницы и HTML-справку.
Веб-справка [2] представляет собой фрагментированный формат вывода HTML в таблицах стилей DocBook XSL , который был представлен в версии 1.76.1. Документация по веб-справке [8] также содержит пример веб-справки и является частью дистрибутива DocBook XSL.
Основными особенностями являются макет страницы, полностью основанный на CSS, поиск по справочному содержимому и оглавление в виде складного дерева. Поиск имеет стемминг , выделение совпадений, явную оценку страниц и стандартный многоязычный токенизатор . Поиск и содержание находятся на панели, которая отображается как набор фреймов , но на самом деле реализована с помощью тегов div и файлов cookie (так что она является прогрессивной).
DocBook предлагает большое количество функций, которые могут оказаться непосильными для нового пользователя. Для тех, кому нужно удобство DocBook без необходимости сложного обучения, был разработан Simplified DocBook . Это небольшое подмножество DocBook, предназначенное для отдельных документов, таких как статьи или официальные документы (т. е. «книги» не поддерживаются). Упрощенное DTD DocBook в настоящее время имеет версию 1.1. [9]
Инго Шварце, автор mandoc OpenBSD , считает , что DocBook уступает семантическому макросу mdoc для страниц руководства . Пытаясь написать конвертер DocBook-to-mdoc (предыдущие преобразователи, такие как docbook-to-man, не охватывают семантические элементы), он обнаруживает, что семантические части «раздуты, избыточны и неполны одновременно» по сравнению с элементами, описанными в мдок. Более того, Шварце считает, что спецификация DocBook недостаточно конкретна в отношении использования тегов, язык не переносим между версиями, груб в деталях и в целом непоследователен. [10]
Норман Уолш — основной автор книги DocBook: The Definitive Guide, официальной документации DocBook. Эта книга доступна в Интернете по адресу GFDL , а также в виде печатной публикации.