OurBigBook DocsIn addition to the basic way of specifying header levels with an explicit level number as mentioned at Section "Header (
\H)", 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
parentargument 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.