Document Structure . Boost , The Boost C++ Libraries BoostBook Documentation Subset , Chapter 47. Quickbook 1.6

Document Structure

Каждый документ должен начинаться с раздела «Информация о документе», который выглядит примерно так:

[article The Document Title
    [quickbook 1.5]
    [version 1.0]
    [id the_document_name]
    [copyright 2000 2002 2003 Joe Blow, Jane Doe]
    [authors [Blow, Joe] [Doe, Jane]]
    [license The document's license]
    [source-mode c++]
]

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

Boostbook также добавляет другой тип документабиблиотекадля документирования библиотек программного обеспечения.

Таким образом, документация для библиотеки «foo» может начаться:

[library Foo
    [quickbook 1.5]
    [id foo]
    [version 1.0]
]

Document Info Attributes

Информационный блок документа имеет несколько различных типов атрибутов. Все они являются факультативными.

Quickbook specific meta data

[quickbook 1.6]

Атрибутбыстрой книгиобъявляет версию быстрой книги, для которой написан документ. При его отсутствии предполагается версия 1.1. Рекомендуется использовать[quickbook 1.6], который является версией, описанной здесь.

Note

Версия для быстрой книги также вносит некоторые изменения в созданную разметку. В частности, идентификаторы, которые автоматически предназначены для заголовков и разделов, отличаются в более поздних версиях. Чтобы свести к минимуму нарушения, можно использовать атрибутрежима совместимостидля создания аналогичной разметки к старой версии:

[article Article that was original
         written in quickbook 1.3
[quickbook 1.6]
[compatibility-mode 1.3]
]

Эта функция не должна использоваться для новых документов, а только для переноса старых документов в новую версию.

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

[source-mode teletype]

Атрибутисходного режимаустанавливает первоначальныйисходный режим. Если он опущен, будет использоваться значение по умолчаниюc++.

Boostbook/Docbook root element attributes

[id foo]

idопределяет идентификатор элемента документа. Если не указано, идентификатор автоматически генерируется из заголовка. Этот идентификатор также используется для генерации вложенных идентификаторов.

[lang en]

Лангопределяет язык документа. Используется для локализации документации. Обратите внимание, что Boostbook не имеет поддержки локализации, поэтому, если вы используете его для создания справочной документации, он будет на английском языке.

Это должен быть языковой код, взятый из ISO 639 (возможно, расширенный кодом страны, взятым из ISO 3166).

[dirname foo]

dirnameиспользуется для указания названия каталога библиотеки в репозитории. Это расширение бустерной книги, поэтому оно действует только для блоков документациибиблиотеки. Он используется для некоторых функций бусбука, но для чистой документации по быстрой книге не имеет практического эффекта.

Docbook Metadata

версия,авторское право,авторы,лицензия,последняя редакцияибиблиодявляются необязательной информацией.

Boostbook Metadata

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

Nesting quickbook documents

Блоки Docinfo могут появляться только в начале файла быстрой книги, поэтому для создания более сложного документа вам нужно использовать несколько файлов быстрой книги и использовать тег, чтобы вставить их. Например, если вы хотите создать книгу с введением и главой, сначала создайте файл для книги:

[book Simple example
[quickbook 1.6]
]
[include introduction.qbk]
[include chapter.qbk]

	Note
	Структурирование документа, подобного этому, было введено в краткую книгу 1.6, поэтому требуется поле`[быстрая книга 1.6]`docinfo.

Соответствующим типом документа для введения являетсяпредисловие, поэтому содержаниевведение.qbkдолжно быть что-то вроде:

[preface Introduction
[quickbook 1.6]
]
Write the introduction to the book here....

Глава:

[chapter A chapter
[quickbook 1.6]
]
Chapter contents....

Sections

Документы Quickbook структурированы с использованием «секций». Они используются для создания таблицы содержимого и при генерации html для разделения документа на страницы. Это необязательно, но хорошая идея для всех, кроме самых простых документов.

Раздельный документ может выглядеть так:

[book Title
    [quickbook 1.5]
]
[section First Section]
[/...]
[endsect]
[section Second Section]
[/...]
[endsect]

Секции начинаются с тегаи заканчиваются тегом[endsect].является комментарием,описано позже.

Разделам может быть предоставлен дополнительный идентификатор:

[#quickbook.ref.id]
[section:id The Section Title]

idбудет именем файла генерируемого раздела. Если его нет, «Заголовок раздела» будет нормализован и станет идентификатором. Действительные символыa-Z,A-Z,0-9и_. Все недействительные символы преобразуются в подчеркивание, а все верхние регистры преобразуются в нижние регистры. Таким образом: «Заголовок раздела» будет нормализован до «заголовок раздела».

Разделы могут гнездиться, и это приводит к иерархии в таблице содержимого.

Статья Document Structure раздела The Boost C++ Libraries BoostBook Documentation Subset Chapter 47. Quickbook 1.6 может быть полезна для разработчиков на c++ и boost.