LaTeX cross refs (obviously) don't work in epub and html

[fuhrmanator]

Thanks for putting this together - it's working very well with LaTeX and pdflatex.

It would be good to point out in https://github.com/wikiti/pandoc-book-template#insert-an-image that cross refs using \ref{} won't work in epub and html output.

I would also like to know if anyone has used this template with https://lierdakil.github.io/pandoc-crossref/ as this would solve some of those problems. I discovered bookdown but it seems very complex, and I'm not sure it's worth it to have the cross references be working in all the outputs. Your template seems way simpler.

[wikiti]

Hi @fuhrmanator !

Thank you for taking your time to create an issue.

You're correct, cross references are not working neither on HTML nor EPUB. Looks like I never checked if they worked correctly, and I assumed that they did.

I'll take a look on that extension you've linked, and see if I can integrate it during the weekend.

[wikiti]

Hi again @fuhrmanator ,

I've taken a look at pandoc-crossref, and, personally, I don't like the requirements to install it (Haskell based? yikes).

I've found this other plugin, pandoc-fignos, which requires python, which is more common on Linux distributions, and users are more familiar with it.

Looks like the syntax is almost identical, so plugins may be interchangeable. Of course, since both require installing additional dependencies, cross-references should be an optional feature that may be toggled manually by changing the Makefile.

What do you think?

[fuhrmanator]

Sounds reasonable. There's so much activity in pandoc/markdown/etc. that it's hard to keep up. I'm happy to use either system but like it when it's simpler to install.

[fuhrmanator]

Looking closer at the solution, I see pandoc-fignos is just figures. There are other projects pandoc-eqnos, pandoc-tablenos, pandoc-secnos, etc. to complete the numbering issues in epubs/html - it's a modular design, but how more complex is having to integrate all those projects as opposed to a Haskell one that's complete?

[wikiti]

Looks like there's a project that integrates all of them, called pandoc-xnos is a suite of all of them. Could be easily installed with a single pip install command. Anyways, since both dependencies use the exact same syntax, they can be interchanged by chaing the Makefile.

I've already tried pandoc-xnos, and seems to work nice (except for this issue). I'll document it on the README.md with both options, update the sample files, and merge back to the master branch.

[wikiti]

@fuhrmanator I gave up trying to use pandoc-xnos since I could not avoid some annoying errors. I gave pandoc-crossref a shot, and it works like a charm (I didn't read the documentation part where they say they have precompiled binaries on the GitHub releases page).

So, I created this PR to update the template using that filter as an optional feature: https://github.com/wikiti/pandoc-book-template/pull/9

Does it suit your needs?

[fuhrmanator]

Thanks for doing this quickly. I'm not (yet) able to install under windows https://github.com/lierdakil/pandoc-crossref -- the released binaries file does nothing, so I'm trying to rebuild it using Haskell. To be continued...

[fuhrmanator]

Alright - it's working! 💯 Turns out, I was thinking the released binary was an install script, when in fact it was the filter :-/ So, didn't need to build with haskell. I did have to update my pandoc, however.

I now am able to see the cross references with hyperlinks that are working in HTML and epub (I use Calibre to verify quickly). The only thing that doesn't appear to work in the 01-introduction.md example are these:

Please, check [First] subsection.

Please, check [this](#first) subsection.

But I think it's because they are not valid. I'm not sure of the former, but the latter should be (#first-images) based on the HTML that is generated.

To verify, the cross references to figure, table and equation, I moved the labels on these examples that appear higher up in the chapter, since I couldn't really verify the hyperlinks in an epub when they point to things on the same "page".

Suggestion: Maybe you can put the makefile option for cross references as a comment? I think a lot of people may look at that as the documentation (?).

[fuhrmanator]

More feedback after trying it with a real project. The numbering scheme works but isn't the same as LaTeX, unfortunately. I wanted to get figures to be numbered inside the chapter/section, e.g., Figure 1.1, 1.2, 2.1, 2.2, etc. since by default it numbers figures 1, 2, 3, etc.

I played around a lot with numbering schemes and I haven't figured out how to get the LaTeX behavior. If you enable numberSections: true in pandoc-crossref, the numbering scheme is to add one to the latest nesting number. So if your figure appears in section 1.4, it will have figure number 1.4.1. If it's in Section 1 (before a subsection has been made), it's figure 1.1. Maybe I can get it to work by defining a template.

Edit -- from the docs:

Please note that at the moment, templates are not supported with LaTeX/PDF output.

Doesn't seem like it's easy to get the same numbering across all the formats.

[wikiti]

Hi @fuhrmanator !

Sorry for the delay.

But I think it's because they are not valid. I'm not sure of the former, but the latter should be (#first-images) based on the HTML that is generated.

You're right. I've corrected them.

Suggestion: Maybe you can put the makefile option for cross references as a comment? I think a lot of people may look at that as the documentation (?).

I've updated the Makefile to include a brief description on the pandoc-crossrefs uncommented filter.

The numbering scheme works but isn't the same as LaTeX, unfortunately.

Looks like they're working on something related on this PR for the next release.

Since this last problem is not related to this template, I'll merge the PR and close this issue.

Please, if you think there is anything left to improve regarding this issue, feel free to re-open it or comment on it.

Best regards, Daniel