OurBigBook
If you use \x within a title, which most commonly happens for image titles, that can generate complex dependencies between IDs, which would either be harder to implement, or lead to infinite recursion.
To prevent such problems, OurBigBook emits an error if you use an \x without content in the title of one of the following elements:
  • any header. For example, the following gives an error:
    = h1
    {id=myh1}
    
    == \x[myh1]
    This could be solved by either adding a content to the reference:
    = h1
    {id=myh1}
    
    == \x[myh1][mycontent]
    or by adding an explicit ID to the header:
    = h1
    {id=myh1}
    
    == \x[myh1]
    {id=myh2}
  • non-header (e.g. an image) that links to the title of another non-header
    For non-headers, things are a bit more relaxed, and we can link to headers, e.g.:
    = h1
    
    \Image[myimg.jpg]
    {title=my \x[h1]}
    This is allowed because OurBigBook calculates IDs in two stages: first for all headers, and only later non non-headers.
    What you cannot do is link to another image e.g.:
    \Image[myimg.jpg]
    {id=myimage1}
    {title=My image 1}
    
    \Image[myimg.jpg]
    {title=my \x[h1]}
    and there the workaround are much the same as for headers: either explicitly set the cross reference content:
    \Image[myimg.jpg]
    {id=myimage1}
    {title=My image 1}
    
    \Image[myimg.jpg]
    {title=my \x[h1][My image 1]}
    or explicitly set an ID:
    \Image[myimg.jpg]
    {id=myimage1}
    {title=My image 1}
    
    \Image[myimg.jpg]
    {id=myimage2}
    {title=my \x[h1]}
    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.
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 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]}
or:
\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.

Ancestors

  1. Cross reference
  2. Macro
  3. OurBigBook Markup
  4. OurBigBook Project