Вы можете включить еще один файл XML с:

[xinclude file.xml]

Это полезно, когда файл.xml был создан Doxygen и содержит ваш справочный раздел.

xinclude пути обычно используются без изменений в сгенерированной документации, которая не будет работать, если вы хотите, чтобы они были относительны к текущему файлу быстрой книги. Quickbook может добавить атрибут xml:base к документации бустера, чтобы указать, где должны быть найдены файлы xinclude. Например, если вы хотите, чтобы они были относительно текущего файла Fastbook:

[article Article with xincludes
[quickbook 1.6]
[xmlbase .]
]
[xinclude file.xml]

Теперь xinclude должен работать, если file.xml находится в том же каталоге, что и файл с быстрой книгой. Хотя это может не работать, если вы распространяете сгенерированные файлы (так как их относительные каталоги могут измениться).

Скажите, что статья генерируется в подкаталоге, запуская что-то вроде:

quickbook article.qbk --output-file=output/article.xml

Это будет генерировать корневой тег бульвара:

<article id="article_with_xincludes"
    last-revision="$Date: 2013/08/20 08:26:48 $"
    xml:base=".."
    xmlns:xi="http://www.w3.org/2001/XInclude">

Поскольку xml:base настроена на .., процессор xml будет знать, чтобы посмотреть в родительском каталоге, чтобы найти file.xml, который поставляется через xi:include.

Пункты начинаются с левого удара и заканчиваются двумя или более новыми линиями. Для пунктов не требуется разметки. QuickBook автоматически обнаруживает пункты из контекста. Блоковые отметины [раздел, эндосект, h1, h2, h3, h4, h5, h6, блюрб, (блок-цитирование) ':', pre, def, table and include ] также могут прекратить действие пункта. Это новый пункт...

Предварительный код начинается с пространства или вкладки. Код будет выделен синтаксисом согласно текущему режиму Источник:

#include <iostream>
int main()
{
    // Sample code
    std::cout << "Hello, World\n";
    return 0;
}

import cgi
def cookForHtml(text):
    '''"Cooks" the input text for HTML.'''
    return cgi.escape(text)

Macros, которые уже определены, расширены в исходном коде. Пример:

[def __array__ [@http://www.boost.org/doc/html/array/reference.html array]]
[def __boost__ [@http://www.boost.org/libs/libraries.htm boost]]
    using __boost__::__array__;

Генераты:

using boost::array;

Внутри кода, кодовые блоки и встроенный код, QuickBook не позволяет любой разметке избегать конфликтов с целевым синтаксисом (например, c++). В случае, если вам нужно переключиться на разметку QuickBook в коде, вы можете сделать это с использованием конкретного языка escape-back delimiter. In C++ and Python, the delimiter is the double del (back-quote): «``» and «``». Пример:

void foo()
{
}

Будут генерировать:

void foo()
{
}

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

Иногда вы не хотите, чтобы какой-то предопределенный текст был рассмотрен как исходный код. В таких случаях используйте [pre...] блок разметки.

[pre
    Some *preformatted* text                    Some *preformatted* text
        Some *preformatted* text            Some *preformatted* text
            Some *preformatted* text    Some *preformatted* text
]

Пространства, вкладки и новинки становятся таковыми. В отличие от всех разметок уровня быстрых блоков, pre (и Code) являются единственными, которые допускают несколько новых линий. Вышеприведенная маркировка будет генерировать:

Some preformatted text                    Some preformatted text
    Some preformatted text            Some preformatted text
        Some preformatted text    Some preformatted text

Обратите внимание, что в отличие от Code, разметка фраз, таких как шрифт, по-прежнему разрешена внутри блоков pre.

[:sometext...]

[note This is a note]
[tip This is a tip]
[important This is important]
[caution This is a caution]
[warning This is a warning]

генерирует DocBook напоминания:

	Note
	Это записка

	Tip
	Это совет

	Important
	Это важно

	Caution
	Это предупреждение

	Warning
	Это - предупреждение

Это единственные напоминания, поддерживаемые DocBook. Так, например, [информация] Это некоторая информация] вряд ли даст желаемый эффект.

[h1 Heading 1]
[h2 Heading 2]
[h3 Heading 3]
[h4 Heading 4]
[h5 Heading 5]
[h6 Heading 6]

Heading 1

Heading 2

Heading 3

Heading 4

Heading 5

Heading 6

Вы можете указать id для заголовка:

[h1:heading_id A heading to link to]

Чтобы связать его, вам нужно будет включить id раздела обложки:

[link document_id.section_id.heading_id The link text]

Хотя вы можете предшествовать заголовку anchor, если хотите использовать независимое местоположение.

Если заголовок не имеет id, то он будет автоматически генерироваться с нормальным именем с name="document_id.section_id.нормализованным_header_text" (т.е. действительные символы a-z, A-Z, 0-9 и _. Все невалидные символы преобразуются в подчеркивание, и все верхняя часть преобразуются в нижнюю. Например: Заголовок 1 в разделе 2 будет нормализован до section_2.heading_1. Вы можете использовать:

[link document_id.section_id.normalized_header_text The link text]

чтобы связать их. Дополнительные сведения см. в разделе Ссылки на сервер и Раздел.

	Note
	Указание заголовка ids - это функция с быстрой книгой 1.6, более ранние версии не поддерживают их.

В случаях, когда вы не хотите заботиться об уровне заголовка (от 1 до 6), вы можете использовать Generic Heading:

[heading Heading]

Generic Heading предполагает уровень, плюс один, самого внутреннего участка, где он размещен. Например, если он помещен в крайнюю часть, то он предполагает h2.

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

[section A]
[h2 X]
[h2:link_id Y]
[h2 Z]
[endsect]

Здесь мы используем h2, предполагая, что раздел А является самым внешним уровнем. Если он помещен на внутреннем уровне, вам придется использовать h3, h4 и т.д. в зависимости от того, где находится раздел. В целом это уровень секции плюс один. Однако довольно утомительно сканировать уровень секции каждый раз. Если переписать пример выше, как показано ниже, это будет автоматически:

[section A]
[heading X]
[heading Y]
[heading Z]
[endsect]

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

[def macro_identifier some text]

Когда определяется макрос, идентификатор заменяет текст где угодно в файле, в пунктах, в разметках и т. д. макро_идентификатор является строкой небелых символов пространства, за исключением '. Макро не может следовать алфавитному характеру или акценту. сменный текст может быть любой фразой (даже отмеченной). Пример:

[def sf_logo [$http://sourceforge.net/sflogo.php?group_id=28447&type=1]]
sf_logo

Теперь везде помещается sf_logo, картина будет встроена.

	Tip
	Это хорошая идея, чтобы использовать макроидентификаторы, которые различимы. Например, в этом документе макроидентификаторы имеют два ведущих и следящих значения (например, __spirit__). Причина заключается в том, чтобы избежать нежелательной замены макроса.

Ссылки (URLS) и изображения являются хорошими кандидатами на макросы. 1 Они имеют тенденцию сильно меняться. Это хорошая идея, чтобы разместить все ссылки и изображения в одном месте рядом с вершиной, чтобы сделать изменения легко. 2 Синтакс не очень хорош. Проще читать и писать, например, __spirit__, чем [@http://spirit.sourceforge.net Spirit].

Еще несколько примеров:

[def :-)            [$theme/smiley.png]]
[def __spirit__     [@http://spirit.sourceforge.net Spirit]]

(См. Images и Links)

Ссылка на эти макросы:

Hi __spirit__  :-)

будет генерировать это:

Привет Спирит

Quickbook имеет некоторые предопределенные макросы, которые вы уже можете использовать.

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

Пример шаблона:

[template person[name age what]
Hi, my name is [name]. I am [age] years old. I am a [what].
]

Template Identifier

Идентификаторы шаблонов могут состоять из:

Formal Template Arguments

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

Формальный аргумент шаблона временно скрывает шаблон того же имени в точке, где шаблон расширяется. Обратите внимание, что тело лица шаблона выше относится к имя age и what как [имя] [возраст] и [что]. имя age и what являются шаблонами, которые существуют в течение времени вызова шаблона.

Template Body

Тело шаблона может быть практически любым блоком QuickBook или фразой. На самом деле есть две формы. Шаблоны могут быть фразой или уровнем блока. Шаблоны Фразы имеют форму:

[template sample[arg1 arg2...argN] replacement text... ]

Шаблоны блоков имеют форму:

[template sample[arg1 arg2...argN]
replacement text...
]

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

Template Expansion

Вы расширяете шаблон таким образом:

[template_identifier arg1..arg2..arg3]

При расширении шаблона вы предоставляете реальные аргументы. Шаблон будет расширен с вашими аргументами. Пример:

[person James Bond..39..Spy]
[person Santa Clause..87..Big Red Fatso]

Что расширится до:

Привет, меня зовут Джеймс Бонд. Мне 39 лет. Я шпион.

Привет, меня зовут Санта Клаус. Мне 87 лет. Я Большой Красный Фатсо.

	Caution
	Предостережение: шаблоны рекурсивны. Шаблон может назвать другой шаблон или даже сам по себе, прямо или косвенно. В QuickBook (пока) нет контрольных структур, поэтому это всегда будет означать бесконечное восстановление. QuickBook может обнаружить эту ситуацию и сообщить об ошибке, если рекурсия превышает определенный предел.

Каждый фактический аргумент может быть словом, фрагментом текста или почти любой фразой QuickBook. Аргументы разделены двойной точкой . и прекращены близким родительским тезисом.

Обратите внимание, что шаблоны и параметры шаблонов не могут быть расширены везде, только там, где текст интерпретируется как фраза. Таким образом, они не могут быть расширены в таких местах, как заголовки таблиц и URL ссылки. Если вы хотите использовать шаблон для создания ссылки на основе параметра шаблона, вы не можете использовать нормальную ссылку и вместо этого должны использовать сбежавший docbook. Пример:

[template boost_ticket[key] '''<ulink url="https://svn.boost.org/trac/boost/ticket/'''[key]'''">#'''[key]'''</ulink>''']
[boost_ticket 2035]

расширится до:

#2035

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

Nullary Templates

Нуллярные шаблоны выглядят и действуют как простые макросы. Пример:

[template alpha[]'''α''']
[template beta[]'''β''']

Расширение:

Some squigles...[*[alpha][beta]]

У нас есть:

αβ

Различие с макросами есть

Пустые скобки после идентификатора шаблона (alpha []) не указывают никаких аргументов. Если тело шаблона не выглядит как список аргументов шаблона, мы можем опустить пустые скобки. Пример:

[template aristotle_quote Aristotle: [*['Education is the best provision
for the journey to old age.]]]

Расширение:

Here's a quote from [aristotle_quote].

У нас есть:

Вот цитата Аристотеля: Образование - лучшее положение для путешествия в старость..

Недостатком является то, что вы не можете избежать пространства между идентификатором шаблона, aristotle_quote, и шаблонным кузовом "Aristotle...". Это пространство будет частью тела шаблона. Если это пространство является нежелательным, используйте пустые скобки или используйте космический выход: «\». Пример:

[template tag\ _tag]

Затем расширяется:

`struct` x[tag];

У нас есть:

struct x_tag;

У тебя есть несколько способов сделать это. Хотя я предпочитаю прямые пустые скобки.

Simple Arguments

Как уже упоминалось, аргументы разделены двойной точкой ".. В качестве альтернативы, если двойная точка не используется и ожидается более одного аргумента, QuickBook использует белое пространство для разделения аргументов, следуя этой логике:

Например:

[template simple[a b c d] [a][b][c][d]]
[simple w x y z]

будет производить:

wxyz

«w x y z» изначально рассматривается как один аргумент, потому что мы не поставляли ». сепараторы. Однако, поскольку простая ожидает 4 аргумента, «w x y z» разрушается итеративно (применяя логику выше), пока у нас нет «w», «x», «y» и «z».

Быстрее! Книга только пытается получить аргументы, которые ей нужны. Например:

[simple w x y z trail]

будет производить:

след wxyz

Аргументы: "w", "x", "y" и "z" след.

	Caution
	Описанное здесь поведение для QuickBook 1.5. В более старых версиях вы можете использовать как двойную точку, так и белое пространство в качестве сепараторов в одном и том же вызове шаблона. Если ваш документ отмечен как более старая версия, он будет использовать старое поведение, которое описано в документации QuickBook 1.4.

Punctuation Templates

С шаблонами одна из наших целей - позволить нам переписать QuickBook в QuickBook (как библиотека qbk). Для того, чтобы это произошло, нам нужно разместить шаблоны пунктуации одного персонажа, которые довольно распространены в QuickBook. Вы, возможно, заметили, что однозначные пунктуации символов разрешены как шаблонные идентификаторы. Пример:

[template ![bar] <hey>[bar]</hey>]

Теперь, расширяя это:

[!baz]

Мы будем:

<hey>baz</hey>

[blurb :-) [*An eye catching advertisement or note...]
    Spirit is an object-oriented recursive-descent parser generator framework
    implemented using template meta-programming techniques. Expression templates
    allow us to approximate the syntax of Extended Backus-Normal Form (EBNF)
    completely in C++.
]

будет генерировать это:

	Note
	Предпочтение призывы, где это уместно.

[table:id A Simple Table
    [[Heading 1] [Heading 2] [Heading 3]]
    [[R0-C0]     [R0-C1]     [R0-C2]]
    [[R1-C0]     [R1-C1]     [R1-C2]]
    [[R2-C0]     [R2-C1]     [R2-C2]]
]

будет генерировать:

Название таблицы является факультативным. Первая строка таблицы автоматически рассматривается как заголовок таблицы; то есть она завернута в теги