If you use an internal link within a
title
argument, that can generate complex dependencies between IDs, which would either be harder to implement, or lead to infinite recursion.To prevent such problems:
- for the case of headers:
- if the internal link text is explicitly given, then it is used to calculate the ID of the title element and on render output
- otherwise, the href argument is used for the ID and the render output. This generally works best when you use magic links.
- for non-headers such as images, you you can link to headers, and the rendered target gets used for both ID and rendered content
Here are some example:
= Hello \x[h2-id][the content] == H2 title {id=h2-id}
- h1 id:
hello-the-content
- h1 render content:
Hello the content
- h1 id:
= Hello \x[h2-id] == H2 title {id=h2-id}
- h1 id:
hello-h2-id
- h1 render content:
Hello h2-id
. Note that this is not very nice due to the-
, but it can be made nicer without repetition with a magic link as in the following example
- h1 id:
= Hello <blue dog> == Blue dog
- h1 id:
hello-blue-dog
- h1 render content:
Hello blue dog
- h1 id:
- non-header (e.g. an image) that links to the title of another non-headerFor non-headers, things are a bit more relaxed, and we can link to headers, e.g.:This is allowed because OurBigBook calculates IDs in two stages: first for all headers, and only later non non-headers.
= h1 \Image[myimg.jpg] {title=my \x[h1]}
What you cannot do is link to another image e.g.:and there the workaround are much the same as for headers: either explicitly set the internal link content:\Image[myimg.jpg] {id=myimage1} {title=My image 1} \Image[myimg.jpg] {title=my \x[h1]}
or explicitly set an ID:\Image[myimg.jpg] {id=myimage1} {title=My image 1} \Image[myimg.jpg] {title=my \x[h1][My image 1]}
TODO both workaround are currently broken Image title with x to image with content incorrectly disallowed, we forgot to add a test earlier on, and things inevitably broke... Should not be hard to fix though, we are just overchecking.\Image[myimg.jpg] {id=myimage1} {title=My image 1} \Image[myimg.jpg] {id=myimage2} {title=my \x[h1]}
While it is technically possible relax the above limitations and give an error only in case of loops, it would require a bit of extra work which we don't want to put in right now: github.com/ourbigbook/ourbigbook/issues/95.
Furthermore, the above rules do not exclude infinite rendering loops, but OurBigBook detects such loops and gives a nice error message, this has been fixed at: github.com/ourbigbook/ourbigbook/issues/34
For example this would contain an infinite loop:
\Image[myimg.jpg]
{id=myimage1}
{title=\x[myimage2]}
\Image[myimg.jpg]
{id=myimage2}
{title=\x[myimage1]}
This infinite recursion is fundamentally not technically solved: the user has to manually break the loop by providing an or:
x
content explicitly, e.g. in either:\Image[myimg.jpg]
{id=myimage1}
{title=\x[myimage2][my content 2]}
\Image[myimg.jpg]
{id=myimage2}
{title=\x[myimage1]}
\Image[myimg.jpg]
{id=myimage1}
{title=\x[myimage2]}
\Image[myimg.jpg]
{id=myimage2}
{title=\x[myimage1][my content 1]}
A closely related limitation is the simplistic approach to
\x
id
output format.