Internal crossreference numbering

[hseg]

Motivation
In technical documents, more things might need numerical crossreferences than just examples (eg, definitions, theorems, lemmata). There are some tantalizing bits of near-support, would like one of them to work for this.

Describe your proposed improvement and the problem it solves.

Current internal referencing syntax seems optimized for internal linking -- so eg one might write see [examples] to create a link to that section. However, there is also room for using internal references for identifiers, a la LaTeX's \label{}/\ref{} feature, where on might write by [lem:PrimesAreRadical], [thm:PolyIsReduced], we have ... -- with the theorem numbers being filled in in place of the link text. In essence, I'm seeing here an opportunity for finally getting a solution to lierdakil/pandoc-crossref#124

Of course, in full generality one might also want control of the prefix of the reference, whether to cite numbers or pages, etc, but this would already be a start.

As concrete syntax, we could use internal links with empty link text (so in effect, this gives a default value for the link text), i.e. [](#thm:PolyIsReduced), however, I'm not certain this is the correct syntax (especially in view of the extensions suggested above)

Describe alternatives you've considered.

At least for LaTeX output, one can work around this lack by using the heavyweight [`\ref{thm:PolyIsReduced}`{=latex}](#thm:PolyIsReduced), but as is clear, this is duplicative, language-dependent, and fragile.

Another possibility is to extend example lists. Three directions suggest themselves:

• Hierarchical references (simple): Prefix example list indexes with the section number, eg flagged as (#@). If we want to be wildly flexible with this, have the number of #'s control the depth of the scope prefixed to the section number
• Hierarchical reference a la Lamport sec 4.2: Enable flagging example list references to be prefixed with their hierachical location
• Multiple counters: Keep track of multiple global counters, eg by prefixing, so we have (thm:@), (lem:@), referenced as Theorem (thm:@:PolyIsReduced).

Note: One may ask -- there are multiple filters that provide multi-counter references? The issue is that either they operate on a closed universe of counters which is too small for me (crossref, xnos, luarefnos -- only provide equations, figures, tables) or require restructuring my text unnaturaly (numbering)

Note: One final counteroffer could be to have me write this as a lua filter. While this is doable, it seems a lot of work to reimplement something that should be doable within pandoc.

Implementation issues

Not all writers support the dynamic references this needs. LaTeX, HTML and friends, and docx seem to be the only ones to support this. OTOH, we could provide the lossy default of just evaluating the appropriate reference and embedding it -- indeed, isn't that what we already do for example lists?

Final notes

I hope the above is coherent -- it is early AM here, and I might be rambling. But this is the one feature that makes me most nostalgic for LaTeX (everything else I already get through the raw embedding escape hatch).

[jgm]

I agree that this would be a great feature. Figuring out the details isn't trivial, though (LaTeX's own label, numbering, and cross-reference system is pretty complex).

See https://github.com/jgm/pandoc/projects/5

[hseg]

On Sat, Jan 06, 2024 at 04:56:47PM -0800, John MacFarlane wrote: I agree that this would be a great feature. Figuring out the details isn't trivial, though (LaTeX's own label, numbering, and cross-reference system is pretty complex). See https://github.com/jgm/pandoc/projects/5

Fair. Reading #813 (comment), it seems this issue can be merged into that, perhaps as a stretch goal -- at the very least, that issue has a better implementation story.