В Quickbook 1.5, если вы включаете файл, который начинается с блока docinfo, он игнорируется. В книге 1.6 это рассматривается как документ, вложенный в текущее положение. Поэтому, если у него есть блок «статья» docinfo, используются теги «статья» в бусбуке.

Он также в основном генерирует ту же разметку, как если бы файл был преобразован отдельно - так, например, генерируются те же идентификаторы, документ обрабатывается с использованием языковой версии, указанной в блоке docinfo. Если язык не указан, он использует по умолчанию (1.1), а не версию документа, который его включил. Это может показаться удивительным, но перезаписывается так, что быстрая книга преобразует его так же, как если бы он был преобразован отдельно.

Таким образом, по большей части, включает в себя с docinfo, как<xinclude>, за исключением нескольких различий. Шаблоны и макросы, определенные в родительском документе, используются в включенном документе, а генератор идентификаторов переписывает идентификаторы, которые сталкиваются между несколькими документами.

Если включенный документ не имеет блока docinfo, он просто включен, как и раньше.

Теперь вы можете расширить макросы в текстовых полях в блоке docinfo. В верхнем блоке docinfo доступны только предопределенные макросы, но в вложенных документах также доступны макросы, определенные в родительском документе.

Здесь есть небольшая ошибка - это утечка в более старые версии для полей<license>и<purpose>, но поскольку доступны только предопределенные макросы, вряд ли удастся взломать какие-либо существующие документы. Поэтому я бы не стал усложнять код, исправляя его.

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

Но это означает, что нет способа определить шаблоны в отдельном файле - полезная функция. Для этого был адаптирован элемент<import>, который также поддерживает файлы быстрой книги. Если файл быстрой книги импортирован, шаблоны и макросы, определенные в нем, добавляются к текущему объему, но ничто другое, содержащееся в этом файле, не используется. Это может быть использовано для создания файлов шаблонов и макробиблиотеки. Это соответствует существующей семантике импорта фрагментов кода.

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

Поскольку<import>теперь поддерживает файлы быстрой книги,<include>также поддерживает исходные файлы. Он включает в себя любую книгу, содержащуюся в комментариях за пределами фрагментов кода. Сниппеты кода в файле доступны для расширения в файле, но ограничены файлом. Точно так же, как когда шаблоны и макросы помещены в файл с быстрой книгой.

Поколение Id в Quickbook 1.5 немного багги, но это не может быть исправлено без переключателя версии, поскольку он разрушит существующие документы. Например, в Quickbook 1.5, когда вы включаете файл Quickbook, он перестает использовать явный идентификатор из информации о документации и генерирует новый идентификатор из заголовка документа для использования.

Генератор идентификаторов в Quickbook 1.6 был улучшен некоторыми другими способами. При генерации идентификаторов из заголовков разделов, заголовков таблиц и т. Д. Он всегда использует источник быстрой книги, а не созданную бустерную книгу для генерации идентификатора. Затем он слегка очищает идентификатор, обрезая ведущие и отстающие подчеркивания и заменяя несколько подчеркиваний одним подчеркиванием. Затем, если вновь созданная часть идентификатора длиннее 32 символов, она усечена.

В то время как новый генератор идентификаторов, как правило, создает лучшие идентификаторы, он с большей вероятностью генерирует дубликаты, поэтому быстрой книге нужно лучше обрабатывать дубликаты. Когда есть несколько идентичных идентификаторов, Quickbook выбирает один для использования на основе списка приоритетов - предпочтительны якоря, затем явные идентификаторы документа и раздела, затем другие явные идентификаторы, за которыми следуют сгенерированные идентификаторы. Затем любые другие явные идентификаторы в документе имеют номера, добавленные во избежание дубликатов - сначала явные идентификаторы в порядке их появления, а затем сгенерированные идентификаторы. Созданный идентификатор, который случайно сталкивается с явным идентификатором, никогда не должен изменять явный идентификатор.

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

Как упоминалось ранее, изменение генератора идентификаторов разорвет ссылки в документах, написанных с использованием старой языковой версии. Для облегчения перехода используется «режим совместимости», для этого просто требуется дополнительный атрибут в docinfo, например, если вы преобразуете документ 1.5 в 1.6:

[article Document
[quickbook 1.6]
[compatibility-mode 1.5]
]

Это означает, что документ будет разбираться как 1,6, используя все новые функции, но идентификаторы (и, возможно, другие разметки) будут генерироваться так же, как и для документа 1.5.

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

Теперь можно использовать теги<quickbook>и<compatibility-mode>в начале файла. До или без информационного блока документа. Это полезно для файлов, содержащих только шаблоны, которые на самом деле не нуждаются в блоке информации о документе.

Если вы не указываете<compatibility-mode>, поведение зависит от того, есть ли у вас блок доцинфо. Если вы делаете это, он использует версию быстрой книги файла, если вы этого не делаете, он наследует режим совместимости родителя, даже если вы указываете версию быстрой книги. Это правильно - смешивание режимов совместимости в документах проблематично. На самом деле было бы ошибкой позволять им указывать внешние блоки.

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

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

[heading:id A heading with an explicit id]

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

Поскольку быстрая книга теперь соответствует квадратным скобкам, она исправит некоторые ошибки. Например,<[*[bold]]>используется для разбора как[смелый- обратите внимание, что закрывающая квадратная скобка не является жирной, теперь она разбирается как[смелый]. В этом случае это просто тонкая визуальная разница, но она может вызвать странные проблемы, например, при вложении в столовую клетку.

Названия таблиц теперь разбираются как фразы, поэтому допускается некоторая разметка:

[table [*bold title]]

Это пустой стол со смелым названием. Название больше не заканчивается новой линией, а либо закрытой квадратной скобкой, либо двумя открывающимися квадратными скобками, которые вы получаете в начале ячеек таблицы, так что теперь это работает:

[table Simple[[heading 1][heading 2]][[cell 1][cell 2]]]

Проблема при использовании тегов<xi:include>в удаленной бусбуке заключается в том, что вы обычно не знаете, в каком каталоге будет находиться файл бусбука, поэтому невозможно использовать относительные ссылки. Это можно исправить, добавив атрибут<xml:base>к тегу документа. Для этого используйте новый атрибут<xmlbase>в блоке docinfo вашего документа. Например, чтобы избежать<xi:include>s относительно каталога файла:

[library Library documentation
[quickbook 1.6]
[xmlbase .]
]

Любые пути в<xinclude>элементах будут соответственно переписаны. Обратите внимание, что большинство документов не нуждаются в этом и, вероятно, не должны использовать его. Используйте его, только если вы абсолютно уверены, что он вам понадобится.

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

[template doesnt_work[]
[ordered_list
    [`code phrase`]
]
]

В этом случае он будет думать, что<[\>'является шаблонным вызовом и дает ошибку разбора. Чтобы обойти это, поставьте сбежавшее пространство перед кодовой фразой:

[template works[]
[ordered_list
    [\ `code phrase`]
]
]

Новые элементы, добавленные в книгу 1.6:

Раньше, если вы использовали элемент в неправильном контексте, он просто не обрабатывался, что было удивительно. Люди часто не понимали, что их элемент не был обработан. Так что теперь это ошибка.

Если бы тело элемента фразы не анализировалось, оно просто использовалось бы без обработки. Измените это, чтобы быть серьезной ошибкой.

1.7 вводит новый<!>тип элемента для установки режима источника одного объекта без изменения режима источника иным образом. Его можно использовать для блоков кода и других элементов. Например:

[!c++]
    void foo() {};
[!python]```def foo():```

Он также может быть использован для установки режима источника для элементов:

[!teletype][table
    [[code][meaning]]
    [[`+`][addition]]
]

При использовании перед разделом он устанавливает режим источника для всего раздела.

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

[!c++]
A declaration `void foo();` and a definition `void foo() {}`.

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

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

[article Some article
[quickbook 1.7]
'''<author>
    <firstname>John</firstname>
    <surname>Doe</surname>
    <email>john.doe@example.com</email>
</author>'''
]

Сбежавшая докбук всегда помещается в конце блока docinfo, поэтому не следует предполагать, что он будет переплетаться с разметкой, генерируемой из быстрой книги. Смесь атрибутов Quickbook и Docbook для одной и той же информации не будет работать хорошо.

Параграфы и блок-элементы теперь можно использовать в списках:

* Para 1
  Para 2
  * Nested Para 1
    Nested Para 2
        Code block
  Para 3

генерирует:

Есть поддержка вызова шаблонов в значениях ссылок, якорях, ролях и включает. Иногда это немного меняется, особенно в местах, где в настоящее время разрешены места, поэтому я могу попробовать использовать немного другую грамматику, где это необходимо. Я думаю, что мне также нужно добавить некоторую проверку, так как парсер может позволить больше символов, чем некоторые из старых.

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

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

[template paras[] Something or other.
Second paragraph.]

Если шаблон фраз содержит только блок-элементы, то он практически неотличим от шаблона блоков. Таким образом, вы получите тот же результат от:

[template foo[] [blurb Blah, blah, blah]]

как:

[template foo[]
[blurb Blah, blah, blah]
]

Если шаблон фразы имеет содержание фразы, смешанное с элементами блока, он будет генерировать выход, как если бы он был расширен в строке.

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

[include sub/*/*.qbk]
[include include/*.h]

Все соответствующие файлы и промежуточные указатели будут совпадать и включены. Паттерн глобуса может быть «*» для соответствия нулю или большему количеству символов, «?» для соответствия одному персонажу, «[-]» для соответствия классу символов, «[^-]» для эксклюзивного соответствия классу символов, «\\», чтобы избежать специального персонажа шара, который затем сопоставляется, и все остальное сопоставляется с персонажем.

	Note
	Из-за побега в ссылках на файл «\\» глобусный побег является двойным «\»; т.е. и избежал обратного слэша.