Документ

Документ

Расширение имени файла	.dbk, .xml
Тип интернет-СМИ	приложение/документ+xml
Разработано	ОАЗИС
Тип формата	язык разметки
Расширено с	СГМЛ , XML
Стандартный	5.1 (ноябрь 2016 г.) , 4,5 (октябрь 2006 г.)
Открытый формат ?	Да

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

Как семантический язык, DocBook позволяет пользователям создавать содержимое документа в нейтральной к представлению форме , которая отражает логическую структуру содержимого; этот контент затем может быть опубликован в различных форматах, включая HTML , XHTML , EPUB , PDF , man-страницы , WebHelp. и HTML-справка , не требуя от пользователей внесения каких-либо изменений в исходный код. Другими словами, когда документ написан в формате DocBook, его можно легко переносить в другие форматы, и его не нужно переписывать.

Дизайн

DocBook — это язык XML . В текущей версии (5.x) язык DocBook формально определяется схемой NG RELAX со встроенными правилами Schematron . (Существуют также версии схемы W3C XML Schema +Schematron и Document Type Definition (DTD), но они считаются нестандартными.)

Как семантический язык, документы DocBook описывают не то, как «выглядит» их содержимое, а скорее значение этого содержимого. Например, вместо того, чтобы объяснять, как можно визуально отформатировать аннотацию статьи, DocBook просто говорит, что конкретный раздел является аннотацией. Внешний инструмент обработки или приложение должны решить, где на странице должна располагаться аннотация и как она должна выглядеть, и следует ли вообще включать ее в окончательный результат.

DocBook предоставляет огромное количество тегов семантических элементов. Они разделены на три широкие категории: структурные, блочные и встроенные.

Структурные теги определяют общие характеристики своего содержимого. book Например, element указывает, что его дочерние элементы представляют части книги. Сюда входят название, главы, глоссарии, приложения и т. д. Структурные теги DocBook включают, помимо прочего:

• set: Озаглавленная коллекция из одного или нескольких bookили articles, могут быть вложены в другие наборы
• book: Титулованный сборник chapterс, articles, и/или partс дополнительными глоссариями, приложениями и т. д.
• part: Озаглавленная коллекция из одного или нескольких chapters — может быть вложен в другие части и может иметь специальный вводный текст.
• article: Озаглавленная ненумерованная коллекция элементов уровня блока.
• chapter: Озаглавленная, пронумерованная коллекция элементов уровня блока — главы не требуют явных номеров, номер главы — это количество элементов предыдущей главы в XML-документе плюс 1.
• appendix: Содержит текст, представляющий приложение.
• dedication: Текст представляет собой обозначение содержащегося структурного элемента.

Структурные элементы могут содержать другие структурные элементы. Структурные элементы — единственные разрешенные элементы верхнего уровня в документе DocBook.

Теги уровня блока — это такие элементы, как абзацы, списки и т. д. Не все эти элементы могут напрямую содержать текст. Последовательные элементы уровня блока визуализируются один «после» другого. After в данном случае может отличаться в зависимости от языка. В большинстве западных языков «после» означает «ниже»: абзацы текста печатаются вниз по странице. Системы письма других языков могут иметь разную направленность ; например, в японском языке абзацы часто печатаются нисходящими столбцами, причем столбцы идут справа налево, поэтому «после» в этом случае будет слева. Семантика DocBook совершенно нейтральна по отношению к такого рода языковым концепциям.

Теги строкового уровня — это такие элементы, как выделение, гиперссылки и т. д. Они оборачивают текст внутри элемента уровня блока. Эти элементы не приводят к разрыву текста при отображении в формате абзаца, но обычно они заставляют процессор документов применять какую-то особую типографскую обработку к заключенному в нем тексту путем изменения шрифта, размера или подобных атрибутов. (В спецификации DocBook говорится , что она предполагает различную типографскую обработку, но она не предлагает конкретных требований относительно того, какой может быть эта обработка.) То есть процессору DocBook не нужно преобразовывать emphasis выделить курсивом . Процессор DocBook на основе чтения может увеличить размер слов, а текстовый процессор может использовать жирный шрифт вместо курсива.

Образец документа

 <?xml version="1.0" encoding="UTF-8"?>
 <book xml:id="simple_book" xmlns="http://docbook.org/ns/docbook" version="5.0">
   <title>Very simple book</title>
   <chapter xml:id="chapter_1">
     <title>Chapter 1</title>
     <para>Hello world!</para>
     <para>I hope that your day is proceeding <emphasis>splendidly</emphasis>!</para>
   </chapter>
   <chapter xml:id="chapter_2">
     <title>Chapter 2</title>
     <para>Hello again, world!</para>
   </chapter>
 </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 как текстовый процессор .

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

История

DocBook зародился в 1991 году в дискуссионных группах Usenet и в конечном итоге стал совместным проектом HAL Computer Systems и O'Reilly & Associates и в конечном итоге породил собственную организацию по техническому обслуживанию (Davenport Group), а затем в 1998 году перешел в консорциум SGML Open , который впоследствии стал ОАЗИС . DocBook в настоящее время поддерживается Техническим комитетом DocBook в OASIS.

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 ), а также работу Проекта документации Linux .

Pre DocBook v5.0

До 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.

Выходные форматы

Файлы DocBook используются для подготовки выходных файлов в самых разных форматах. Почти всегда это достигается с помощью таблиц стилей DocBook XSL . Это таблицы стилей XSLT , которые преобразуют документы DocBook в ряд форматов ( HTML , XSL-FO для последующего преобразования в PDF и т. д.). Эти таблицы стилей могут быть достаточно сложными для создания оглавлений, глоссариев и указателей. Они могут контролировать выбор определенных частей основного документа для создания различных версий одного и того же документа (например, «учебника» или «краткого справочного руководства», где каждая из них состоит из подмножества материала). Пользователи могут писать свои собственные таблицы стилей или даже полноценную программу для обработки DocBook в соответствующем выходном формате в соответствии с их потребностями.

Норман Уолш и команда разработчиков проекта DocBook поддерживают ключевое приложение для создания выходных данных из исходных документов DocBook: набор таблиц стилей XSLT (а также устаревший набор таблиц стилей DSSSL ), которые могут генерировать высококачественный HTML и печатать ( FO / PDF ). вывод, а также вывод в других форматах, включая RTF , справочные страницы и HTML-справку.

Веб-справка — это формат вывода фрагментированного HTML в таблицах стилей DocBook XSL , который был представлен в версии 1.76.1. Документация для веб-справки также предоставляет пример веб-справки и является частью дистрибутива DocBook XSL.

Основными особенностями являются макет страницы, полностью основанный на CSS, поиск по справочному содержимому и оглавление в виде складного дерева. Поиск имеет стемминг , выделение совпадений, явную оценку страниц и стандартный многоязычный токенизатор . Поиск и содержание находятся на панели, которая отображается как набор фреймов , но на самом деле реализована с помощью тегов div и файлов cookie (так что она является прогрессивной).

Упрощенный документ

DocBook предлагает большое количество функций, которые могут оказаться непосильными для нового пользователя. Для тех, кому нужно удобство DocBook без необходимости сложного обучения, Simplified DocBook был разработан . Это небольшое подмножество DocBook, предназначенное для отдельных документов, таких как статьи или официальные документы (т. е. «книги» не поддерживаются). Упрощенное DTD DocBook в настоящее время имеет версию 1.1.

Критика

Инго Шварце, автор OpenBSD mandoc , считает , что DocBook уступает семантическому макросу mdoc для man-страниц . Пытаясь написать конвертер DocBook-to-mdoc (предыдущие преобразователи, такие как docbook-to-man, не охватывают семантические элементы), он обнаруживает, что семантические части «раздуты, избыточны и неполны одновременно» по сравнению с элементами, описанными в мдок. Более того, Шварце считает, что спецификация DocBook недостаточно конкретна в отношении использования тегов, язык не переносим между версиями, груб в деталях и в целом непоследователен.

См. также

• Список языков разметки документов
• Сравнение языков разметки документов
• Документ XSL
• Дарвиновская архитектура типизации информации
• LinuxDoc
• Латекс
• Мумия

Дальнейшее чтение

Норман Уолш — основной автор книги DocBook: The Definitive Guide , официальной документации DocBook. Эта книга доступна в Интернете по адресу GFDL , а также в виде печатной публикации.

• Норман Уолш (июнь 2010 г.). DocBook 5: Полное руководство (2-е изд.). О'Рейли Ассошиэйтс. ISBN  978-0-596-80502-9 .
• Боб Стейтон (2005). DocBook XSL: Полное руководство (3-е изд.). Сейджхилл Энтерпрайзис. ISBN  0-9741521-2-9 .
• Джо Брокмайер (2001). Публикация DocBook — лучший способ создания профессиональных документов . Серия Linux от Prima Tech. ISBN  0-7615-3331-1 .

Внешние ссылки

• DocBook.org — сборник информации DocBook, включая версии DocBook 4.x и 5.0: The Definitive Guide и все версии схем/DTD DocBook.
• Репозиторий DocBook в OASIS — нормативный дом схемы/DTD DocBook.
• Страница проекта DocBook XSL на SourceForge.net , таблицы стилей XSLT 1.0 для DocBook на GitHub
• HOWTO по демистификации DocBook
• DocBook: The Definitive Guide, 1-е издание, версия 2.0.6 — PDF-файл с полной закладкой руководства для DocBook 3.x и 4.x.
• Написание с использованием элементов DocBook .