OurBigBook Docs
The
\Include macro allows including an external OurBigBook headers under the current header.It exists to allow optional single page HTML output while still retaining the ability to:
- split up large input files into multiple files to make renders faster during document development
- suggest an optional custom output split with one HTML output per OurBigBook input, in order to avoid extremely large HTML pages which could be slow to load
\Include takes one mandatory argument: the ID of the section to be included, much like internal links.There is however one restriction: only the toplevel headers can be pointed to. This restriction allows us to easily find the included file in the filesystem, and dispenses the need to do a first
./ourbigbook run to generate the ID database. This works because the ID of the first header is derived from the filename.Headers of the included document are automatically shifted to match the level of the child of the level where they are being included.
If
--embed-includes is given, the external document is rendered embedded into the current document directly, essentially as if the source had been copy pasted (except for small corrections such as the header offsets).Otherwise, the following effects happen:
- The headers of the included tree appear in the table of contents of the document as links to the corresponding external files.This is implemented simply by reading a previously generated database file much like cross file internal link internals, which avoids the slowdown of parsing all included files every time.As a result, you have to do an initial parse of all files in the project to extract their headers however, just as you would need to do when linking to those headers.
- the include itself renders as a link to the included document
--embed-includes
Here is an example of inclusion of the files The above is the recommended and slightly insaner version of:The insaner version is a bit insaner because the
not-index.bigb and not-index-2.bigb:\Include[not-index]
\Include[not-index-2]
\Include[not-index-with-scope]\Include[not-index]
\Include[not-index-2]
\Include[not-index-with-scope]\Include magically discards the following newline node that follows it if it just a plaintext node containing exactly a newline. With a double newline, the newline would already have been previously taken out on the lexing stage as part of a paragraph.Section "
\Include example" shows what those actually render like.