[WIP] Custom label prefixes

[lierdakil]

Work towards #84.

At the time of writing, tests pass, but scoping rules remain unimplemented and code really needs some clean-up. Also, worth mentioning that coverage isn't 100%, so some corner cases might be broken.

Since there's no documentation at the moment, and everything can change without advance warnings, you can dump default pandoc-crossref-related metadata options with

pandoc -F pandoc-crossref -t markdown -s /dev/null

(you can replace /dev/null with an empty text file on Windows)
Here's what it dumps at the moment of writing: https://gist.github.com/lierdakil/d5e51a5b077b0b3152f8345926aa6b25

TODO (in no particular order):

• New metadata format

• Referencing arbitrary divs and spans

• Referencing YAML arrays in templates (via $$var[i][j]$$)

• Scoping rules

• Local variable overrides for the purpose of templating (via prefix attributes, object attributes)

• Update subfigures to allow sub-anything

• Subfigure (or rather sub-anything) collected captions

• Override-able captions for list-of-stuff

• Referencing YAML objects in templates (via $$var[i][j]$$)

• Align LaTeX output with other output formats (probably use caption, subcaption, newfloat)

  For now, it makes the most sense to treat LaTeX as any other output format. This should (mostly) work for the purpose of PDF output, but the resulting LaTeX code wouldn't be much different from a plaintext file. Anyway, reimplementing pandoc-crossref algorithms in LaTeX might be a fun challenge, but it will take an unreasonable amount of time. LaTeX gurus are welcome to help out.

• Per-output-format setting overrides

• Way to disable default predefined prefixes

• Update (rewrite) docs

• Fix subfigures without grid (captions not shown)

• Investigate figures/subfigures in ODT (captions not shown?)

  While the original issue is worked around in 2035f42. There are some issues with ODT output, namely ODT writer attempts to add figure and table numbers
  itself, which kinda breaks everything for pandoc-crossref. See thread on pandoc-discuss for discussion.

• Fix subcaption table style in LaTeX? (lines above and below the table)

• Access arbitrary scope properties from templates

• Number and string literals in template variables (for indexed access)

• Metadata variable name disambiguation?

  Currently implemented via optionally scoping all pandoc-crossref setting under crossref metadata variable. There might be a better solution.

Issues from v0.4 milestone

• Numbering parts? Numbering parts? #187

• Customize reference prefix delimiter Customizable reference prefix delimiter (i.e. ability to replace : with something else for output) #200

• How to get figure caption like "Figure 1.3-1 ..." "chapDelim" usage, how to get a figure caption like "Figure 1.3-1 Something"? #185

• Configurable caption placement (above/below) Customization: captions above instead of below in some blocks #178

  Might be a better idea to make divs fully templated?

• Short captions for use in list-of Short captions for use in list-of? #162

LaTeX-specific:

• Do not set prefix defaults with cleveref do not set prefix defaults with cleveref #189
  Actually, do not do any cleveref set-up if it's already enabled.
• Pass nameinlink to cleveref when appropriate [LaTeX] Pass nameinlink to cleveref when appropriate #203
• Use subcaption instead of subfig For subfigures in LaTeX: subfig incompatible with hyperref -> use subcaption instead? #182

[Luca-wj]

Could you please let me know when pandoc-crossref v4 can be updated to be built with Pandoc latest

[lierdakil]

At this point, it's probably safe to assume this PR is more or less dead. The branches diverged considerably, and I unfortunately have neither bandwidth nor strong motivation to continue with this branch. The best bet would probably be to try and port over the good ideas from this PR to the main branch (and not all of them are good!). I'll be very happy to review a PR if one materializes. If not, I'll look into it as time allows, but as time goes by, it seems I get less and less spare time -- maybe it's just me getting old.

[hanjoosten]

At this point, it's probably safe to assume this PR is more or less dead. The branches diverged considerably, and I unfortunately have neither bandwidth nor strong motivation to continue with this branch. The best bet would probably be to try and port over the good ideas from this PR to the main branch (and not all of them are good!). I'll be very happy to review a PR if one materializes. If not, I'll look into it as time allows, but as time goes by, it seems I get less and less spare time -- maybe it's just me getting old.

Hi @lierdakil , this is sad to hear, but totally understandable as well. We all have limited time, and too much to do. That said, In our project we have been hoping for this PR to bring us further. A couple of years ago, you asked me to explain what we were looking for particularly, which I did (See AmpersandTarski/Ampersand#1264 (comment)) .
To be honest, I don't see myself diving into the details of pandoc-crossref, because I suppose that would require a significant learning investment. I also respect the fact that your time is limited as well. But maybe you still see some possibilities for our use case. If you don't, I would totally understand. A reaction is much appreciated.

[lierdakil]

In principle, it should be feasible to add references to arbitrary divs to the main branch. However, there are some roadblocks which require a considerable time investment:

• Reference prefixes (so fig: etc) are hard-coded in the main branch. Now, it's not impossible to add user-defined ones on top, but it's not necessarily straightforward either.
• LaTeX poses a problem, at least as long as we're looking to support proper LaTeX references.

Now, If we don't care about LaTeX being "proper", i.e. no \ref or \cref, just hard-coded numbers and links, it'll simplify things significantly.

Another distinct possibility is exposing an API for defining custom references entirely programmatically -- which will save me from worrying about mapping things to/from YAML. So, for the sake of argument, imagine we have a typeclass like this:

class ReferenceDefinition a where
  prefix :: Text --^ The prefix used to disambiguate, e.g. "dfn" or "thm"
  title :: a -> Block -> Maybe [Inline] --^ extract the item title from the Div
  content :: a -> Index -> [Block] -> [Block] --^ arbitrarily modify the content of the Div
  reference :: a -> Index -> Citation -> [Inline] --^ how to render references

(I didn't spend a lot of time thinking about it, so this is more for illustration purposes than an actual proposed API, it'll have to be a fair bit more complicated in practice)

Then implementing this for some data structure and passing it along to runCrossRef would use this definition to handle Divs with the corresponding prefix in the identifier (and references to those divs, naturally).

The upside is this is quite doable, practically speaking. The downside is it puts the onus of actually defining sensible rendering on the user of the library.

Now, whether I find time to implement something like this in the observable future is an open question. If I do, it'll be a small miracle. But let me know if this all sounds vaguely sensible for your use case.