[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):

• [X] New metadata format

• [X] Referencing arbitrary divs and spans

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

• [X] Scoping rules

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

• [X] Update subfigures to allow sub-anything

• [ ] Subfigure (or rather sub-anything) collected captions

• [x] Override-able captions for list-of-stuff

• [x] 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

• [x] 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.

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

• [x] Access arbitrary scope properties from templates

• [x] 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

• [X] Numbering parts? #187

• [ ] Customize reference prefix delimiter #200

• [ ] How to get figure caption like "Figure 1.3-1 ..." #185

• [x] Configurable caption placement (above/below) #178

  Might be a better idea to make divs fully templated?

• [ ] Short captions for use in list-of #162

~~LaTeX-specific:~~

• [ ] ~~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 #203~~
• [ ] ~~Use subcaption instead of subfig #182~~

[hanjoosten]

The failure of this build on appveyor is probably related to https://github.com/fpco/stackage/issues/3385

[lierdakil]

https://github.com/commercialhaskell/stack/issues/3944#issuecomment-385809670

[hanjoosten]

Hi,

I am really looking foreward to using this feature in my application. However, as long as the network problem isn't solved, I guess this is not going to released. I would be very grateful if it is possible to release this version as it was in commit c758ddeecf03ec317eb676e3d034c9b286b4af9e. I need this version to be known in hackage as well, for the users of my application build it with stack.

cheers!

[lierdakil]

Network problem is not an issue as far as I am concerned, but this PR is WIP until I find time to whip it into shape.

https://github.com/lierdakil/pandoc-crossref/pull/174/commits/cd338a17030b2dad1d7e4ed4b3e678e3d927e8a9 is available via git tag https://github.com/lierdakil/pandoc-crossref/releases/tag/v0.4.0.0-alpha1, and I'm not inclined to publish this mess to Hackage precisely because it's a bit of a mess right now.

The regular release for GHC 8.4 and Pandoc 2.2 is on Hackage as v0.3.2.0 (which is virtually identical to v0.3.1.0 except for version bounds and some minor tweaks)

[lierdakil]

If you really want to subject your users to alpha code, I think you could add git tags to extra-deps?

[hanjoosten]

Ahh. Sorry! I thought only the network problem was causing delay. I'll be patient 😃

[srnnkls]

I tried 0.4.0.0a to achieve something similar to https://github.com/lierdakil/pandoc-crossref/issues/175. While it works great for referencing to html-id atributes, somehow the template in my yaml header isn't recognized anymore.

Edit: Also doesn't work with a pandoc-crossref.yaml. All fine on 0.3.2.0 though.

[lierdakil]

@sorennikolaus, feel free to open a new issue. Not entirely sure what you mean by "template in your yaml header". If you could spell out what you did, what you expected to happen and what did actually happen that would be great, thanks.

Just in case, template settings were moved to prefix definitions, so instead of figureTemplate you have

prefixes:
  fig:
    captionTemplate: ...

and instead of figPrefixTemplate

prefixes:
  fig:
    referenceTemplate: ...

Also, pandoc-crossref.yaml in the current directory works for me. The format is changed though, see the gist in OP.

Bear in mind that the resulting config is a merge of YAML objects of the following description: documentMeta ♢ dirConfig ♢ formatConfig ♢ globalConfig ♢ defaultMeta where

• (♢) is left-biased left-associative recursive merge operation
• documentMeta is YAML header
• dirConfig is YAML config read from $CWD/pandoc-crossref.yaml where $CWD is current working directory
• formatConfig is config read from $HOME/.pandoc-crossref/config-$FMT.yaml where $HOME is user's home directory and $FMT is Pandoc's output format string (e.g. html, latex, etc)
• globalConfig is config read from $HOME/.pandoc-crossref/config.yaml
• defaultConfig is the config baked into the executable, see the gist in OP.

Also, prefix configurations use some defautls in case requried properties are not defined anywhere.

[srnnkls]

Okay, thank you! I hadn't noticed the change in the metadata syntax. That works really good.

One more things for now:

And can I somehow extend the scope for caption placement (in case there is one defined in the metadata) to <span> elements as well? That would allow: [Caption]{prefix:label} for environments that cannot be nested.

[lierdakil]

You can reference arbitrary div or span identifiers provided there's a prefix defined, so for example [some text]{#fig:1} [@fig:1] will be rendered as equivalent to [some text]{#fig:1} fig. 1. Moreover, the last paragraph in divs is interpreted as caption, so

:::{#fig:1}
something

Caption
:::

will turn into

:::{#fig:1}
something

Figure 1: Caption
:::

That said, there's no obvious thing that could be unambiguously interpreted as a caption in spans, so those tend to go caption-less. In the current iteration, you can see this if you try something like this:

[something]{#fig:1}

[@fig:1]

\listof{fig}

will turn into

[something]{#fig:1}

fig. 1

List of Figures
===============

1.  

(notice it's just 1., without caption). This should be remedied somehow, but I don't have any particular ideas at the moment. Say, for math, it might be reasonable to just use the math itself in place of a caption for the purpose of the list of equations.

There is also no unambiguous way to actually place the caption with inline elements even if it was defined somehow. If you have any ideas, feel free to share those. I'd ask you to create a separate issue for that though, because keeping track of stuff is hard as it is, frankly.

[hanjoosten]

@lierdakil , I see progress lately. Makes me happy! Without any intent of pushing you, could you please elaborate on what is still left to be done for this pull request, if there is any? Thanks!

[lierdakil]

@hanjoosten, sorry for being silent. Long story short, I found some time to start implementing scoping rules, which ultimately resulted in a massive rewrite. While doing that, I kinda broke subfigures and chapters. Doing the latter is relatively easy with scoping, but the former isn't. Besides those, lists-of-stuff need some attention, as discussed above, and LaTeX output also needs some love -- it's currently broken in places, and compared to what pandoc-crossref can currently do with other output formats, it's, well, anaemic, to put it politely. And then I need to rewrite documentation. Also, probably a few bugs still lurking (and I'm pretty sure I added some just now). So... yeah, a fair bit needs to be done still.

[hanjoosten]

Thanks for the update. These things take time, which is scarse to most people. Keep up the good work. If it helps your motivation, I just want to let you know that we have a good use case for custom labels in our open source project. Good luck!

[slochower]

Does this PR address the ability to change the citation prefix for certain sections? (I'm asking here because I don't think this is explicitly mentioned in any of the issues, but is related to a bunch.) For example, the final section could be an Appendix, might need to restart the Figure counter and use the style Figure A1, A2, A3, ...

Edit: I should add that I did see #95, but my impression is that would work to prefix all figure captions in a separate document and in that case, I'm not sure how cross-referencing between the main text Markdown and the SI Markdown would work. I'm working with the main text and SI together.

[lierdakil]

@slochower, there are a couple methods for overriding certain properties on per-something basis. In particular, there are ways to access "scope properties" from template. So... yes, with a bit of creative thinking, say, having separate prefixes for primary sections and appendices, this should be relatively straightforward.

[slochower]

Oh, neat. A quick check of the documentation doesn't pull up anything for "scope." Do you have a super quick/minimal example of how that might work? Then I can try to take it from there...

[lierdakil]

A quick check of the documentation doesn't pull up anything for "scope."

Documentation for this PR is basically nonexistent at this point, so that's not a surprise, considering general scoping is only introduced here.

Do you have a super quick/minimal example of how that might work?

Hmm. Not directly. There are two related examples (well, actually, tests). See scoping test and part numbering test.

The most straightforward way to get something like you describe is probably just scoping everything over appendix, specifying a custom label for said appendix and adding scope index to the item index. Something like this:

---
pagetitle: asd
prefixes:
  app:
    from: sec
    title: Appendix
    ref: 
      - app.
      - apps.
captionIndexTemplate: $$s.i$$$$ri$$
scope:
  - app
...

# Section 1 {#sec:1}

![Section 1 fig](img.png){#fig:sec1fig}

# Section 2 {#sec:2}

![Section 2 fig](img.png){#fig:sec2fig}

# Appendix 1 {#app:1 label=A}

![Appendix 1 fig](img.png){#fig:app1fig}

# References

- @sec:1
- @sec:2
- @app:1

---

- @fig:sec1fig
- @fig:sec2fig
- @fig:app1fig

There are other ways to get something like this. That said, I think this needs a little refinement still.

[slochower]

Thanks for the MWE. That is helpful. I appreciate it :)