In addition to the basic way of specifying header levels with an explicit level number as mentioned at Section "Header , OurBigBook also supports a more indirect ID-based mechanism with the "
parent
argument of the \H
element.We hightly recommend using
parent
for all but the most trivial documents.For example, the following fixed level syntax:
is equivalent to the following ID-based version:
= My h1
== My h2 1
== My h2 2
=== My h3 2 1
= My h1
= My h2 1
{parent=my-h1}
= My h2 2
{parent=my-h1}
= My h3 2 1
{parent=my-h2-h}
The main advantages of this syntax are felt when you have a huge document with very large header depths. In that case:
- it becomes easy to get levels wrong with so many large level numbers to deal with. It is much harder to get an ID wrong.
- when you want to move headers around to improve organization, things are quite painful without a refactoring tool (which we intend to provide in the browser editor with preview), as you need to fix up the levels of every single header.If you are using the ID-based syntax however, you only have to move the chunk of headers, and change the
parent
argument of a single top-level header being moved.
Note that when the
because the second header has level
parent=
argument is given, the header level must be 1
, otherwise OurBigBook assumes that something is weird and gives an error. E.g. the following gives an error:
= My h1
== My h2
{parent=my-h1}
2
instead of the required = My h2
.When scopes are involved, the rules are the same as those of internal reference resolution, including the leading
/
to break out of the scope in case of conflicts.Like the
which is equivalent to:
\H
child
argument, parent
also performs ID target from title on the argument, allowing you to use the original spaces and capitalization in the target as in:
= Flying animal
= Bat
{parent=Flying animal}
= Flying animal
= Bat
{parent=flying-animal}
See also: Section 2. "Header explicit levels vs nesting design choice" for further rationale.