I have a specific document I'm trying to process which causes Prince to run forever; this occurs in both Prince for Books and in the latest version of the core product.

When running Prince in verbose mode, the logging suggests that it reaches the end of the document, then just tries to resolve cross-references forever. The resulting log looks like this:

prince: Resolving cross-references...
prince: Resolving cross-references...
prince: Resolving cross-references...
prince: Resolving cross-references...
prince: Resolving cross-references...

... and on without end, potentially for hours if I just let it run. Enabling debugging messages isn't much more informative – it results in the following:

prince: Resolving cross-references...
prince: debug: pack
prince: Resolving cross-references...
prince: debug: pack
prince: Resolving cross-references...
prince: debug: pack
prince: Resolving cross-references...
prince: debug: pack
prince: Resolving cross-references...
prince: debug: pack

The document in question makes extensive use of cross-references with generated content; I suspect, but cannot prove, that what's going in here is that the generated content for some cross-reference somewhere in the document is causing the thing it's referring to to be bumped to the next page, which changes its page number, which modifies the original cross reference in such a way that it no longer causes a page break, which pulls the thing it's referring to back to its original page, and so on, and so on. However, since I can't see the rendered PDF output, I'm not sure where this might be happening, if indeed it's the culprit.

Can anyone offer any suggestions regarding how to chase this one down? I unfortunately have not been successful in producing a contrived test case that replicates the issue, and the document in question is not one I'm at liberty to publicly share at this time.

The latest build should now detect this situation and halt, although it still requires manual intervention to fix.

Yep, that was indeed the culprit – the terminal digit of an inline page number which appeared on a tight-fitting line was wobbling between a zero and a one; when it was a 0, the resulting page break was shoving the following heading to the next page, bumping every following section to the next page and turning the 0 into a 1, which meant the line didn't break anymore, which turned the page number's terminal digit back to a 0, and so forth.

It's helpful that the warning message identifies which specific anchors are affected, since the culprit in this scenario pretty much has to be somewhere between the last unaffected anchor and the first affected one. However, in this case the affected anchors numbered in the dozens, and the way the list is presented in the warning message makes it quite awkward to parse when the number of affected anchors is large. In the following warning message:

prince: warning: References to counter value may be incorrect: [...]

... would it be possible to have each anchor annotated with the line number on which it appears in the input document? e.g.:

prince: warning: References to counter value may be incorrect: #foo(page):137, #bar(page):44, #baz(page):119

(i.e., in this example meaning that whatever element #foo is targeting appears on line 137 of the input document, and so forth.)

Being able to see at a glance which affected anchor is the earliest appearing in the input document would have made chasing this one down a lot easier.

Edited 17 Nov 2023 by David J Prokopetz

We have updated this in the latest build to give page numbers for potentially affected cross-references and also added a new fail-safe option (--fail-incorrect-references) that will give an error if cross-references cannot be resolved (although this is probably more useful to catch issues in automated workflows, you would rather see the generated PDF while working on it and a warning is fine for that).

Fantastic. I currently have no means of reproducing the issue to check out the new warning messages, but it sounds like that's exactly what I needed in this case. I appreciate the quick action on this one!

This fix has also been included in Prince 15.3.