``
#include

int main(void) {
puts("hello, world");
}
``
{title=C hello world}
]]

= Comment
{parent=Macro}
{title2=`\Comment`}

The `Comment` and `comment` macros are regular macros that does not produce any output. Capitalization is explained at: {full}.

You will therefore mostly want to use it with a [literal argument], which will, as for any other macro, ignore any macros inside of it.
\OurBigBookExample[[[
Before comment.

\Comment[[
Inside comment.
]]

After comment.
]]]

And an inline one:
\OurBigBookExample[[[
My inline \comment[[inside comment]] is awesome.

\comment[[inside comment]] inline at the start.
]]]

= Header
{parent=Macro}
{title2=`\H`}

with `= ` (equal sign space):
``
= My h1

== My h2

=== My h3
``
Insane headers end at the first newline found. They cannot therefore contain raw newline tokens.

Equivalent sane:
``
\H[1][My h1]

\H[2][My h2]

\H[3][My h3]
``

Custom ID for on insane headers:
``
= My h1
{id=h1}

== My h2
{id=h2}

=== My h3
{id=h3}
``

Sane equivalent:
``
\H[1][My h1]{id=h1}

\H[2][My h2]{id=h2}

\H[3][My h3]{id=h3}
``

= Unlimited header levels
{parent=Header}

There is no limit to how many levels we can have, for either sane or insane headers!

HTML is randomly limited to `h6`, so OurBigBook just renders higher levels as an `h6` with a `data-level` attribute to indicate the actual level for possible CSS styling:
``

My title

The recommended style is to use insane headers up to `h6`, and then move to sane one for higher levels though, otherwise it becomes very hard to count the `=` signs.

To avoid this, we considered making the insane syntax be instead:
``
= 1 My h1
= 2 My h2
= 3 My h3
``
but it just didn't feel as good, and is a bit harder to type than just smashing `=` n times for lower levels, which is the most common use case. So we just copied markdown.

= My h3
{parent=Unlimited header levels}

= My h4
{parent=My h3}

= My h5
{parent=My h4}

= My h6
{parent=My h5}

= My h7
{parent=My h6}

= My h8
{parent=My h7}

= My h9
{parent=My h8}

= My h10
{parent=My h9}

= My h11
{parent=My h10}

= My h12
{parent=My h11}

= My h13
{parent=My h12}

= Skipping header levels
{parent=Header}

The very first header of a document can be of any level, although we highly recommend your document to start with a `\H[1]`, and to contain exactly just one `\H[1]`, as this has implications such as:
* `\H[1]` is used for the document title:
* `\H[1]` does not show on the

After the initial header however, you must not skip a header level, e.g. the following would give an error because it skips level 3:
``
= my 1

== my 1

==== my 4
``

= The toplevel header
{parent=Header}

= Toplevel header
{synonym}

The toplevel header of a OurBigBook file is its first header and the one with the lowest level, e.g. in a document with recommended syntax:
``
= Animal

== Dog

=== Bull Terrier

== Cat
``
the header `= Animal` is the tolevel header.

Being the toplevel header gives a header some special handling described in child sections of the section and elsewhere throughout this documentation.

The toplevel header is only defined if the document has only a single header of the highest level. e.g. like the following has only a single `h2`:
``
== My 2

=== My 3 1

=== My 3 2
``

= The toplevel header IDs don't show
{parent=The toplevel header}

Header IDs won't show for the toplevel level. For example, the headers would render like:
``
My 2

1. My 3 1

2. My 3 2
``
rather than:
``
1. My 2

1.2. My 3 1

1.2. My 3 2
``
This is because in this case, we guess that the `h2` is the toplevel.

= The ID of the first header is derived from the filename
{parent=The toplevel header}

TODO: we kind of wanted this to be the ID of the toplevel header instead of the first header, but this would require an extra postprocessing pass (to determine if the first header is toplevel or not), which might affect performance, so we are not doing it right now.

When the OurBigBook input comes from a file (and not e.g. ), the default ID of the first header in the document is derived from the basename of the OurBigBook input source file rather than from its title.

This is specially relevant when [including] other files.

For example, in file named `my-file.bigb` which contains:
``
= Awesome ourbigbook file
``
the ID of the header is `my-file` rather than `awesome-ourbigbook-file`. See also: .

If the file is an other than , then the basename of the parent directory is used instead, e.g. the toplevel ID of a file:
``
my-subdir/README.bigb
``
would be:
``
#my-subdir
``
rather than:
``
#README.bigb
``

For the toplevel index file however, the ID is just taken from the header itself as usual. This is done because you often can't general control the directory name of a project.

For example, a [GitHub pages] root directory must be named as `.github.io`. And users may need to rename directories to avoid naming conflicts.

As a consequence of this, the toplevel index file cannot [be included in other files].

= `\H` arguments
{parent=Header}

= `\H` `c` argument
{parent=H arguments}

If given, makes the header capitalized by default on .

More details at: {full}.

= `\H` `child` argument
{parent=H arguments}
{tag=`multiple` argument}
{tag=Disabled macro argument}

This marks given IDs as being children of the current page.

The effect is the same as adding the <\x child argument> argument to an under the header. Notably, such marked target IDs will show up on the autogenerated .

This argument is deprecated in favor of the .

Example:
``
= Animal

== Mammal

=== Bat

=== Cat

== Wasp

== Flying animal
{child=bat}
{child=wasp}

\x[bat]

\x[wasp]
``
renders exactly as:
``
= Animal

== Mammal

=== Bat

=== Cat

== Wasp

== Flying animal

\x[bat]{child}

\x[wasp]{child}
``

The header `child` syntax is generally preferred because at some point while editing the content of the header, you might accidentally remove mentions to e.g. `\x[bat]{child}`, and then the relationship would be lost.

The <\H tag argument> does the same as the <\x child argument> but in the opposite direction.

= `\H` `file` argument
{parent=H arguments}

If given, the current section contains metadata about file or other resource with the given URL.

If empty, the URL of the file is extracted directly from the header. Otherwise, the given URL is used.

for example:
``
= path/to/myfile.c
{file}

An explanation of what this file is about.
``
renders a bit like:
```
= path/to/myfile.c
{id=_file/path/to/myfile.c}

An explanation of what this file is about.

\a[path/to/myfile.c]

``
// Contents of path/to/myfile.c
int main() {
return 1;
}
``
```
so note how:
* does not normalize the path, e.g. it does not convert `/` to `-`.

Also, a <_file output directory>[`_file/` prefix] is automatically added to the ID. This is needed with to avoid a collision between:
* `path/to/myfile.c`: the actual file
* `_file/path/to/myfile.c`: the metadata about that file. Note that locally the `.html` extension is added as in `file/path/to/myfile.c.html` which avoids the collision. But on a server deployment, the `.html` is not present, and there would be a conflict if we didn't add that `file/` prefix.
* a link to the is added automatically, since users won't be able to click it from the header, as clicking on the header will just link to the header itself
* a preview is added. The type of preview is chosen as follows:
* if the URL has an image extension, do an preview
* otherwise if the URL has a video extension, or is a YouTube URL, do a preview
* otherwise, don't show a preview, as we don't know anything sensible to show

In some cases however, especially when dealing with external URLs, we might want to have a more human readable title with a non empty `file` argument:
``
The video \x[tank-man-by-cnn-1989] is very useful.

= Tank Man by CNN (1989)
{c}
{file=https://www.youtube.com/watch?v=YeFzeNAHEhU}

An explanation of what this video is about.
``
which renders something like:
``
The video \x[tank-man-by-cnn-1989] is very useful.

= Tank Man by CNN (1989)
{id=_file/https://www.youtube.com/watch?v=YeFzeNAHEhU}

\Video[https://www.youtube.com/watch?v=YeFzeNAHEhU]

An explanation of what this video is about.
``

To make to `{file}` headers, use the <`\x` `file` argument>.

= `\H` `file` argument toplevel header
{parent=H file argument}

To create a separate file with the <`\H` `file` argument> set on the , you must put it under the special <`_file` input directory>. For example:
``
_file/path/to/myfile.txt.bigb
``
could contain something like:
``
= myfile.txt
{file}

Description of my amazing file.
``
and it would be associated to the file:
``
path/to/myfile.txt
``

The content of the header `= myfile.txt` is arbitrary, as it can be fully inferenced from the file path `_file/path/to/myfile.txt.bigb`. TODO add linting for it. Perhaps we should make adding a header be optional and auto-generate that header instead. But having at least an optional header is good as a way of being able to set header properties like .

= `_file` input directory
{parent=H file argument}

See: <`\H` `file` argument toplevel header>{full}.

= `\H` `file` argument demo
{parent=H file argument}

This section contains some live demoes of the <`\H` `file` argument>.

= file_demo
{file}
{parent=H file argument demo}

An explanation of what this directory is about.

= file_demo/file_demo_subdir
{file}
{parent=H file argument demo}

Going deeper.

= file_demo/hello_world.js
{file}
{parent=H file argument demo}

An explanation of what this text file is about.

Another line.

= file_demo/file_demo_subdir/hello_world.js
{file}
{parent=H file argument demo}

Going deeper.

= index.js
{file}
{parent=H file argument demo}
{tag=Overview of files in this repository}

This is a central source file that basically contains all the functionality of the , so basically the -to-[whatever] (e.g. [HTML]) conversion code, including parsing and rendering.

Things that are not there are things that only use markup conversion, e.g.:
* : does conversion from command line
*

This file must be able to run in the browser, so it must not contain any Node.js specifics.

It exposes the central `convert` function for markup conversion.

You should normally use the packaged `_obb/ourbigbook.js` version of this file when using ourbigbook as an external dependency.

This file is large, and large text files are not previewed, as they would take up too much useless vertical space and disk memory/bandwidth.

= file_demo/my.bin
{file}
{parent=H file argument demo}

Binary files are not rendered.

= Tank_man_standing_in_front_of_some_tanks.jpg
{file}
{parent=H file argument demo}

An explanation of what this image is about.

Another line.

= Tank Man by CNN (1989)
{c}
{file=https://www.youtube.com/watch?v=YeFzeNAHEhU}
{parent=H file argument demo}

An explanation of what this video is about.

= `\H` `numbered` argument
{c}
{parent=H arguments}
{tag=Boolean argument}

This determines whether renderings of a header will have section numbers or not. This affects all of:
* themselves
* links
* with the <\x full argument>
This option can be set by default for all files with:

By default, headers are numbered as in a book, e.g.:
``
= h1

== h2

=== h3

==== h4
``
renders something like:
``
= h1

Table of contents
* 1. h2
* 1.1. h3
* 1.1.1. h4

== 1. h2

=== 1.1. h3

==== 1.1.1. h4
``

However, for documents with a very large number of sections, or [deeply nested headers] those numbers start to be more noise than anything else, especially in the table of contents and you are better off just referring to IDs. E.g. imagine:
``
1.3.1.4.5.1345.3.2.1. Some deep level
``

When documents reach this type of scope, you can disable numbering with the `numbered` option.

This option can be set on any header, and it is inherited by all descendants.

The option only affects descendants.

E.g., if in the above example turn numbering off at `h2`:
``
= h1

== h2
{numbered=0}

=== h3

==== h4
``
then it renders something like:
``
= h1

Table of contents
* 1. h2
* h3
* h4

== 1. h2

=== h3

==== h4
``

The more common usage pattern to disable it on toplevel and enable it only for specific "tutorial-like sections". An example can be seen at:
* https://cirosantilli.com/[]: huge toplevel wiki, for which we don't want numbers
* https://cirosantilli.com/x86-paging[]: a specific tutorial, for which we want numbers
which is something like:
``
= Huge toplevel wiki
{numbered=0}

== h2

=== A specific tutorial
{numbered}
{scope}

==== h4

===== h5
``
then it renders something like:
``
= Huge toplevel wiki

Table of contents
* h2
* A specific tutorial
* 1. h4
* 1.1. h5

== h2

=== A specific tutorial

==== 1. h4

===== 1.1. h5
``
Note how in this case the number for `h4` is just `1.` rather than `1.1.1.`. We only show numberings relative to the first non-numbered header, because the `1.1.` wouldn't be very meaningful otherwise.

= `\H` `parent` argument
{c}
{parent=H arguments}

= ID-based header levels
{c}
{synonym}
{title2}

In addition to the basic way of specifying header levels with an explicit level number as mentioned at {full}, 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:
``
= My h1

== My h2 1

== My h2 2

=== My h3 2 1
``
is equivalent to the following ID-based version:
``
= 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 ), 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 `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}
``
because the second header has level `2` instead of the required `= My h2`.

When 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 <\H child argument>, `parent` also performs on the argument, allowing you to use the original spaces and capitalization in the target as in:
``
= Flying animal

= Bat
{parent=Flying animal}
``
which is equivalent to:
``
= Flying animal

= Bat
{parent=flying-animal}
``

See also: {full} for further rationale.

= ID-based header levels and scope resolution
{c}
{parent=H parent argument}

When mixing both <\H parent argument> and , things get a bit complicated, because when writing or parsing, we have to first determine the parent header before resolving scopes.

As a result, the follow simple rules are used:
* start from the last header of the highest level
* check if the `{parent=XXX}` is a suffix of its ID
* if not, proceed to the next smaller level, and so on, until a suffix is found

Following those rules for example, a file `tmp.bigb`:
``
= h1
{scope}

= h1 1
{parent=h1}
{scope}

= h1 1 1
{parent=h1-1}

= h1 1 2
{parent=h1-1}

= h1 1 3
{parent=h1/h1-1}

= h1 2
{parent=h1}
{scope}

= h1 2 1
{parent=h1-2}
{scope}

= h1 2 1 1
{parent=h1-2/h1-2-1}
``
will lead to the following header tree with <--log headers>:
``
= h1 tmp
== h2 1 tmp/h1-1
=== h3 1.1 tmp/h1-1/h1-1-1
=== h3 1.2 tmp/h1-1/h1-1-2
=== h3 1.3 tmp/h1-1/h1-1-3
== h2 2 tmp/h1-2
=== h3 2.1 tmp/h1-2/h1-2-1
==== h4 2.1.1 tmp/h1-2/h1-2-1/h1-2-1-1
``

= Header explicit levels vs nesting design choice
{parent=H parent argument}

Arguably, the language would be even saner if we did:
``
\H[My h1][

Paragraph.

\H[My h2][]
]
``
rather than having explicit levels as in `\H[1][My h1]` and so on.

But we chose not to do it like most markups available because it leads to too many nesting levels, and hard to determine where you are without tooling.

Ciro later "invented" (?) <\H parent argument>, which he feels reaches the perfect balance between the advantages of those two options.

= `\H` `scope` argument
{parent=H arguments}

= Scope
{synonym}

In some use cases, the sections under a section describe inseparable parts of something.

For example, when documenting an experiment you executed, you will generally want an "Introduction", then a "Materials" section, and then a "Results" section for every experiment.

On their own, those sections don't make much sense: they are always referred to in the context of the given experiment.

The problem is then how to get unique IDs for those sections.

One solution, would be to manually add the experiment ID as prefix to every subsection, as in:
``
= Experiments

See: \x[full-and-unique-experiment-name/materials]

== Introduction

== Full and unique experiment name

=== Introduction
{id=full-and-unique-experiment-name/introduction}

See our awesome results: \x[full-and-unique-experiment-name/results]

For a more general introduction to all experiments, see: \x[introduction].

=== Materials
{id=full-and-unique-experiment-name/materials}

=== Results
{id=full-and-unique-experiment-name/results}
``

but this would be very tedious.

To keep those IDs shorter, OurBigBook provides the `scope` property of , which works analogously to C++ namespaces with the header IDs.

Using `scope`, the previous example could be written more succinctly as:
``
= Experiments

See: \x[full-and-unique-experiment-name/materials]

== Introduction

== Full and unique experiment name
{scope}

=== Introduction

See our awesome results: \x[results]

For a more general introduction to all experiments, see: \x[/introduction].

=== Materials

=== Results
``

Note how:
* full IDs are automatically prefixed by the parent scopes prefixed and joined with a slash `/`
* we can refer to other IDs withing the current scope without duplicating the scope. E.g. `\x[results]` in the example already refers to the ID `full-and-unique-experiment-name/materials`
* to refer to an ID outside of the scope and avoid name conflicts with IDs inside of the current scope, we start a reference with a slash `/`

So in the example above, `\x[/introduction]` refers to the ID `introduction`, and not `full-and-unique-experiment-name/introduction`.

= `scope` resolution
{parent=H scope argument}

When nested scopes are involved, resolution peels off the scopes one by one trying to find the closes match, e.g. the following works as expected:
``
= h1
{scope}

== h2
{scope}

=== h3
{scope}

\x[h2]
``
Here OurBigBook:
* first tries to loop for an `h1/h2/h3/h2`, since `h1/h2/h3` is the current scope, but that ID does not exist
* so it removes the `h3` from the current scope, and looks for `h1/h2/h2`, which is still not found
* then it removes the `h2`, leading to `h1/h2`, and that one is found, and therefore is taken

= Directory-based `scope`
{parent=H scope argument}

Putting files in subdirectories of the build has the same effect as adding a to their top level header.

Notably, all headers inside that directory get the directory prepended to their IDs.

The toplevel directory is determined as described at: .

= Test scope 1
{parent=H scope argument}
{scope}

For fun and profit.

= Test scope 2
{parent=Test scope 1}
{scope}

Let's break this local link: \a[ourbigbook].

= Not scoped
{parent=Test scope 2}

= `\H` `scope` argument of toplevel headers
{parent=H scope argument}

When is given the `scope` property OurBigBook automatically uses the file path for the scope and heaves fragments untouched.

For example, suppose that file `full-and-unique-experiment-name` contains:
``
= Full and unique experiment name
{scope}

== Introduction

== Materials
``

In this case, multi-file output will generate a file called `full-and-unique-experiment-name.html`, and the URL of the subsections will be just:
* `full-and-unique-experiment-name.html#introduction`
* `full-and-unique-experiment-name.html#materials`
instead of
* `full-and-unique-experiment-name.html#full-and-unique-experiment-name/introduction`
* `full-and-unique-experiment-name.html#full-and-unique-experiment-name/materials`

Some quick interactive cross file link tests:
*
*
*

= `\H` `splitDefault` argument
{parent=H arguments}
{tag=Boolean argument}

When using , always point to non-split pages as mentioned at .

If the `splitDefault` is given however:
* the split header becomes the default, e.g. `index.html` is now the split one, and `nosplit.html` is the non-split one
* the header it is given for, and all of its descendant headers will use the split header as the default internal cross target, unless the header is already rendered in the current page. This does not propagate across however.

For example, consider `README.bigb`:
``
= Toplevel
{splitDefault}

\x[h2][toplevel to h2]

\x[notreadme][toplevel to notreadme]

\Include[notreadme]

== h2
``
and `notreadme.bigb`:
``
= Notreadme

\x[h2][notreadme to h2]

\x[notreadme][notreadme to notreadme h2]

== Notreadme h2
``
Then the following links would be generated:
* `index.html`: split version of `README.bigb`, i.e. does not contain `h2`
* `toplevel to h2`: `h2.html`. Links to the split version of `h2`, since `h2` is also affected by the `splitDefault` of its parent, and therefore links to it use the split version by default
* `toplevel to notreadme`: `notreadme.html`. Links to non-split version of `notreadme.html` since that header is not `splitDefault`, because `splitDefault` does not propagate across includes
* `nosplit.html` non-split version of `README.bigb`, i.e. contains `h2`
* `toplevel to h2`: `#h2`, because even though `h2` is `splitDefault`, that header is already present in the current page, so it would be pointless to reload the split one
* `toplevel to notreadme`: `notreadme.html`
* `h2.html` split version of `h2` from `README.bigb`
* `notreadme.html`: non-split version of `notreadme.bigb`
* `notreadme to h2`: `h2.html`, because `h2` is `splitDefault`
* `notreadme to notreadme h2`: `#notreadme-h2`
* `notreadme-split.html`: split version of `notreadme.bigb`
* `notreadme to h2`: `h2.html`, because `h2` is `splitDefault`
* `notreadme to notreadme h2`: `notreadme.html#notreadme-h2`, because `notreadme-h2` is not `splitDefault`

The major application of this if you like work with a huge `README.bigb` containing thousands of random small topics.

Splitting those into separate source files would be quite laborious, as it would require duplicating IDs on the filename, and setting up .

However, after this README reaches a certain size, page loads start becoming annoyingly slow, even despite already loading large assets like video only on hover or click: the annoying slowness comes from the loading of the HTML itself before the browser can jump to the ID.

And even worse: this README corresponds to the main index page of the website, which will make what a large number of users will see be that slowness.

Therefore, once this README reaches a certain size, you can add the `splitDefault` attribute to it, to make things smoother for readers.

And if you have a smaller, more self-contained, and highly valuable tutorial such as https://cirosantilli.com/x86-paging[], you can just split that into a separate `.bigb` source file.

This way, any links into the smaller tutorial will show the entire page as generally desired.

And any links from the tutorial, back to the main massive README will link back to split versions, leading to fast loads.

This feature was implemented at: https://github.com/ourbigbook/ourbigbook/issues/131

Note that this huge README style is not recommended however. used to do it, but moved away from it. The currently recommended approach is to manually create not too large subtrees in each page. This way, readers can easily view several nearby sections without having to load a new page every time.

= `\H` `splitSuffix` argument
{parent=H arguments}

If given, add a custom suffix to the output filename of the header when using .

If the given suffix is empty, it defaults to `-split`.

For example, given:
``
= my h1

== my h2
``
a `--split-headers` conversion would normally place `my h2` into a file called:
``
my-h2.html
``
However, if we instead wrote:
``
== my h2
{splitSuffix}
``
it would not be placed under:
``
my-h2-split.html
``
and if we set a custom one as:
``
== my h2
{splitSuffix=asdf}
``
it would go instead to:
``
my-h2-asdf.html
``

This option is useful if the root of your website is written in OurBigBook, and you want to both:
* have a section that talks about some other project
* host the documentation of that project inside the project source tree

For example, https://cirosantilli.com with source at https://github.com/cirosantilli/cirosantilli.github.io has a quick section about OurBigBook: https://cirosantilli.com#ourbigbook[].

Therefore, without a custom suffix, the split header version of that header would go to https://docs.ourbigbook.com[], which would collide with this documentation, that is present in a separate repository: https://github.com/ourbigbook/ourbigbook[].

Therefore a `splitSuffix` property is used, making the split header version fall under `/ourbigbook-split`, and leaving the nicer `/ourbigbook` for the more important project toplevel.

If given on the , which normally gets a suffix by default to differentiate from the non-split version, it replaces the default `-split` suffix with a custom one.

For example if you had `notindex.bigb` as:
``
= Not index
``
then it would render to:
``
notindex-split.bigb
``
but if you used instead:
``
= Not index
{splitSuffix=asdf}
``
then it would instead be:
``
notindex-asdf.bigb
``

= `\H` `synonym` argument
{parent=H arguments}

= Synonym
{synonym}

This option is similar to <\H title2 argument> but it additionally:
* creates a new ID that you can refer to, and renders it with the alternate chosen title
* the rendered ID on is the same as what it is a synonym for
* the synonym header is not rendered at all, including in the
* when using , a redirect output file is generated from the synonym to the main ID

Example:
``
= Parent

== GNU Debugger
{c}

= GDB
{c}
{synonym}

I like to say \x[gdb] because it is shorter than \x[gnu-debugger].
``
renders something like:
``
= GNU Debugger

I like to say \a[#gnu-debugger][GDB] because it is shorter than \x[#gnu-debugger][GNU Debugger].
``
Furthermore, if is used, another file is generated:
``
gdb.html
``
which contains a redirection from `gdb.html` to `gnu-debugger.html`.

Implemented at: https://github.com/ourbigbook/ourbigbook/issues/114

= `\H` `title` argument
{parent=H synonym argument}
{tag=`title` argument}

Contains the main content of the header. The :
``
= My title
``
is equivalent to the sane:
``
\H[1][My title]
``
and in both cases `My title` is the title argument.

The <`title` argument> is also notably used for .

= Automatic ID from title
{parent=H title argument}

If a [non-toplevel] macro has the `title` argument is present but no explicit `id` argument is given, an is created automatically from the `title`, by applying the following transformations:
* do a conversion on the title to remove for example any HTML tags that would be present in the conversion output
* convert all characters to lowercase. This uses . Note that this does convert non-ASCII characters to lowercase, e.g. `É` to `é`.
* if is `true` (the default) do . This converts e.g. `é` to `e`.
* if is `true` (the default) do . This converts e.g. `+` to `plus`.
* convert consecutive sequences of all non `a-z0-9` ASCII characters to a single hyphen `-`. Note that this leaves non-ASCII characters untouched.
* strip leading or trailing hyphens
Note how those rules leave non-ASCII Unicode characters untouched, except for:
* capitalization changes wher applicable, e.g. `É` to `é`
as capitalization and determining if something "is a letter or not" in those cases can be tricky.

For toplevel headers, see: .

So for example, the following automatic IDs would be generated: .

\Table[
|| title
|| id
|| latin normalization
|| punctuation normalization
|| comments

| My favorite title
| my-favorite-title
|
|
|

| Ciro's markdown is awesome
| ciro-s-markdown-is-awesome
|
|
| `'` is an ASCII character, but it is not in `a-z0-9`, therefore it gets converted to a hyphen `-`

| É你
| e你
| true
|
| The Latin https://en.wikipedia.org/wiki/Acute_accent[acute accented] `e`, `É`, is converted to its lower case form `é` as per the .

Then, due to , `é` is converted to `e`.

The Chinese character `你` is left untouched as Chinese characters have no case, and no ASCII analogue.

| É你
| é你
| false
|
| Same as the previous, but `é` is not converted to `e` since is turned off.

| C++ is great
| c-plus-plus-is-great
|
| true
| This is the effect of .

| I \i[love] dogs.
| i-love-dogs
|
|
| `love` is extracted from the italic tags `love` with conversion.

| β Centauri
| beta-centauri
|
|
| Our Latin normalization is amazing and knows Greek!
]
{title=Examples of automatically generated IDs}

For [the toplevel header], its ID is derived from the basename of the OurBigBook file without extension instead of from the `title` argument.

TODO:
* maybe we should also remove some or all non-ASCII punctuation. All can be done with `\\p{IsPunctuation}`: https://stackoverflow.com/questions/13925454/check-if-string-is-a-punctuation-character but we need to check that we really want to remove all of them.

= ID target from title
{c}
{parent=H synonym argument}

This conversion type is similar to , but it is used in certain cases where we are targeting IDs rather than setting them, notably:
* <\H parent argument>
* <\H child argument>
* <\H tag argument>

= `\H` `title2` argument of a synonym header
{parent=H synonym argument}

Unlike <\H title2 argument>, the synonym does not show up by default next to the title. This is because we sometimes want that, and sometimes not. To make the title appear, you can simply add an empty `title2` argument to the synonym header as in:
``
= GNU Debugger
{c}

= GDB
{c}
{synonym}
{title2}

= Quantum computing

= Quantum computer
{synonym}
``
which renders something like:
``
= GNU Debugger (GDB)

= Quantum computing
``
Note how we added the synonym to the title only when it is not just a simple flexion variant, since `Quantum computing (Quantum computer)` would be kind of useless would be kind of useless.

= `\H` `tag` argument
{c}
{parent=H arguments}
{tag=multiple argument}

= Tag
{synonym}

Same as <\x child argument> but in the opposite direction, e.g.:
``
== Mammal

=== Bat
{tag=flying-animal}

=== Cat

== Flying animal
``
is equivalent in every way to:
``
== Mammal

=== Bat

=== Cat

== Flying animal
{child=bat}
``

Naming rationale:
* `parent` as the opposite of child is already taken to be then "main parent" via the "<\H parent argument>"
* we could have renamed the <\H child argument> to `tags` as in "this header tags that one", but it would be a bit confusing `tags` vs `tag`
So `child` vs `tag` it is for now.

You generally want to use `tag` instead of the <\H child argument> because otherwise some very large header categories are going to contain Huge lists of children, which is not very nice when editing.

It is possible to enforce the <\H child argument> or the <\H tag argument> in a given project with the option.

= `\H` `title2` argument
{parent=H arguments}
{tag=multiple argument}

The `title2` argument can be given to any element that has the `title` argument.

Its usage is a bit like the `description=` argument of , allowing you to add some extra content to the header without affecting its ID.

Unlike `description=` however, `title2` shows up on all <\x full argument>[`full`] references, including appearances in the , which make it more searchable.

Its primary use cases are:
* give acronyms, or other short names names of fuller titles such as mathematical/programming notation

One primary reason to not use the acronyms as the main section name is to avoid possible ID ambiguities with other acronyms.
* give the header in different languages

For example, given the OurBigBook input:
``
= Toplevel

The Toc follows:

== North Atlantic Treaty Organization
{c}
{title2=NATO}

\x[north-atlantic-treaty-organization]

\x[north-atlantic-treaty-organization]{full}
``
the rendered output looks like:
``
= Toplevel

The ToC follows:

* North Atlantic Treaty Organization (NATO)

== North Atlantic Treaty Organization (NATO)

North Atlantic Treaty Organization

Section 1. "North Atlantic Treaty Organization (NATO)"
``

Related alternatives to `title2` include:
* <\H disambiguate argument> when you do want to affect the ID to remove ambiguities
* <\H synonym argument>

Parenthesis are added automatically around all rendered `title2`.

The `title2` argument has a special meaning when applied to a with the <\H synonym argument>, see <\H title2 argument of a synonym header>.

\Comment[[
= `\H` `tutorial` argument
{parent=h-arguments}
{tag=boolean-argument}

This option is a convenience helper for the common use case of "writting a tutorial". The same would also apply to a report, or an article.
]]

= `\H` `toplevel` argument
{parent=H arguments}
{tag=Boolean argument}

When the `\H` `toplevel` argument is set, the header and its descendants will be automatically output to a separate file, even without <--split-headers>.

For example given:

animal.bigb
``
= Animal

== Vertebrate

=== Dog
{toplevel}

==== Bulldog

== Invertebrate
``

and if you convert as:
``
ourbigbook animal.bigb
``
we get the following output files:
* `animal.html`: contains the headers: "Animal", "Vertebrate" and "Invertebrate", but not "Dog" and "Bulldog"
* `dog.html`: contains only the headers: "Dog" and "Bulldog"

This option is intended to produce output identical to using and separate files, i.e. the above is equivalent to:

animal.bigb
``
= Animal

== Vertebrate

\Include[dog]

== Invertebrate
``

dog.bigb
``
= Dog
{toplevel}

== Bulldog
``

Or in other words: of each source file gets `{toplevel}` set implicitly for it by default.

This design choice might change some day. Arguably, the most awesome setup is on in which source files and outputs are completely decoupled. also essentially wants this, as ideally we want to store one source per header there in each DB entry. We shall see.

= `\H` `wiki` argument
{parent=H arguments}

If given, show a link to the Wikipedia article that corresponds to the header.

If a value is not given, automatically link to the Wiki page that matches the header exactly with spaces converted to underscores.

Here is an example with an explicit wiki argument:

``
==== Tiananmen Square
{wiki=Tiananmen_Square}
``

which looks like:

= Tiananmen Square
{id=wiki-explicit}
{parent=H wiki argument}
{wiki=Tiananmen_Square}

or equivalently with the value deduced from the title:

``
= Tiananmen Square
{wiki}
``

which looks like:

= Tiananmen Square
{id=wiki-implicit}
{parent=H wiki argument}
{wiki}

You can only link to subsections of wiki pages with explicit links as in:

``
= History of Tiananmen Square
{{wiki=Tiananmen_Square#History}}
``

which looks like:

= History of Tiananmen Square
{id=wiki-explicit-subsection}
{parent=H wiki argument}
{{wiki=Tiananmen_Square#History}}