Referencing for diagrams and variations

[dormerod]

This is a long term issue which I'm noting for later on.

In TeX, you can refer to a named figure and all the numbering will update automatically if new figures are inserted or removed in between. Ideally GPub should do something similar so that authors can refer to a specific variation elsewhere in the text, without having to worry about the numbers changing if a variation is added or deleted elsewhere.

One idea is to use the same notation Glift uses to refer to nodes (i.e. 1.1.1.2) and let GPub set the figure names automatically. Some authors might find that a bit difficult, but it would be robust and there's probably no better way when working in an SGF editor.

This isn't a blocking issue for Relentless. We can work around this for now.

[artasparks]

Couple of ideas:
We could overload markdown's link functionality: [Diagram 1](13.1.1.2). Also, diagram ID generation should be stable, so that could be used. But that won't change the relevant diagram. It's pretty clear to me that Go book generation is complicated enough that some node-level METADATA is probably going to be necessary. Perhaps something like? {diagram-ref:13.1.1.2}

As a side note, I believe --debug will display the path to the node and can easily be changed if it doesn't.

[dormerod]

I had a look at the debug output and there is some information about the node path there. If it were going to be used regularly by authors, for this purpose, it could potentially be made clearer and easier to parse.

Using the markdown link functionality is an interesting idea if you don't think that's too much of a hack. It would be nice for readers if the references to other variations were linked in digital versions of books and the markdown formatting seems relatively intuitive for authors.

For now, with Relentless, I'm just marking all places where we'd refer to another variation with 'VARIATION X' and I'll go back and add either hard or soft references in those places later (depending on where things are at), when the book is almost finished.