pandoc-crossref
pandoc-crossref copied to clipboard
lierdakil
chapters option not respected in TeX
If chapters: true, then in HTML every figure is numbered with the section number as prefix.
However, in TeX this is not respected. That is,
{#fig:figure}
is still numbered 1 in Section 1 and not 1.1.
With LaTeX output, rendering is offloaded to LaTeX. I believe if you run Pandoc with --chapters, LaTeX will use x.y format. Or just include arbitrary LaTeX commands via header-includes.
If run
- with
--top-level-division=sectionandchapters: falsethen nothing changes, whereas - with
--top-level-division=sectionandchapters:truethe compilerpdftexthrows an error, and - with
--top-level-division=chapters, the compilerpdftexthrows an error.
I'm pretty sure you're supposed to use pdflatex or xelatex, but maybe it's just me. Anyway, I'd like to see the error.
Also, bear in mind that pandoc-crossref 0.2.x is incompatible with Pandoc 2.0. Beta version is available though, check the releases page
I am sorry, pdflatex was meant. I am also sorry for the wrong information. After a clean up of old compiled files, in particular the *.toc files, the options--top-level-division=section and chapters:true compile fine. However, nothing changes. It is still Figure 1. There is nothing in the TeX file that says otherwise. The example figure in the source code is
\begin{figure}
\centering
\includegraphics{./images/figure.png}
\caption{figure}\label{fig:figure}
\end{figure}
This makes sense, as for example the section is
\section{5 Sample Section}\label{sample-section}
That is, the numbering is done by hand by pandoc-crossref filter, and NOT by the TeX compiler. Therefore, pandoc-crossref should also number the figures explicitly to avoid inconsistencies.
If numbersections = true (a TeX option passed to pandoc), then necessarily numberSections = false if the output is TeX. This is also not respected, as pandoc-crossref will create double headings if both are true (in respecting the idea of pandoc that the same document exports to many output formats.)
That's probably because you need --top-level-division=chapter? But let me reiterate, pandoc-crossref v0.2.7.0 does not work with pandoc 2.0, either downgrade to Pandoc 1.19 or use pandoc-crossref v0.3.0.0-beta3a (or later)
pandoc-crossref's section numbering is a hack. I don't exactly remember why that was needed when I implemented it, but probably for something silly, e.g. to generate human-readable Markdown without crossref-specific syntax or something. Always prefer Pandoc's section numbering (--number-sections) or something output format-specific (custom template, reference docx, custom css, etc)
If you just want to disable LaTeX-specific behavior in pandoc-crossref, run it through a pipe:
pandoc -t json ... | pandoc-crossref | pandoc -f json -t latex ...
Yes, this is compiled with Pandoc 1.19.2.1. No, the document class is scrartcl and thus the correct top-level-division is section.
But without crossref, how to refer to equations in HTML for example, even in general? Is this also built into pandoc now? That was my main motion to use crossref.
Sigh... section numbering is a hack. I.e. numberSections metadata option. I'm not suggesting you don't use pandoc-crossref at all. Just saying you should prefer Pandoc's section numbering when possible.
Ok. In any case, this issue is not about the numberSections being hacky or not, but about the figure numbering not working as it should under pandoc 1.19.1.2 and crossref 0.27.
Figure out how to configure LaTeX to do what you want. Since you're apparently using non-standard template, I can't say anything else. Or use pandoc-crossref through a pipe (so that it doesn't know it's outputting to LaTeX) if you don't care for proper LaTeX references and are fine with just text.
There is a misunderstanding: I know how to configure LaTeX so that it references figures section-wise. The point of pandoc, and supposedly crossref, is that this can be configured in pandoc for various output formats. Not only HTML say, but also pdf via TeX. That is, how to set up pandoc and crossref (but not by modifying the TeX file compiled by pandoc and crossref) so that figures are referenced section-wise in TeX, as the chapters option in crossref alleges.
Why do I find repeating myself I wonder? LaTeX is special. There's no way to make stuff work for arbitrary templates, it's much easier to deal with it client-side, so to speak. Hence the disconnect. I sincerely doubt it would help anything if I spent X days from my already-busy schedule implementing the feature that would break in more than half of real-world cases. Special LaTeX treatment can be avoided by using pandoc-crossref as a JSON pipe directly. I've shown above how. It might not always produce the best results, however, especially with more "out there" things like subfigures etc. Pandoc 2 supports other PDF engines that might do a better job.
What is great about crossref is that numberSections respects sectionDepth for all output formats, whereas pandoc's numbersections only respects sectiondepth in TeX.
How about making crossref use numbersections and sectiondepth if the output is TeX, but use numberSections and sectionDepth otherwise? If not in general, make it an option?
If you say that numberSections is silly but there is a reason for its existence, it is perhaps the lack of the support of sectiondepth for other output formats?
As a corollary, this way, the section-wise figure numbering could be done by the pdflatex compiler instead of crossref.
I assume you mean secnumdepth, and not sectiondepth? Using numbersections would be a bit of a hack, actually, since setting it from metadata won't work in most output formats.
So... okay, setting a couple variables isn't that hard, I guess? Although there's no 1:1 correspondence between crossref's sectionDepth and LaTeX's secnumdepth.
I also have the problem that by setting chapters: true, the figures are still numbered Figure 1, Figure 2,... instead of Figure 1.1, Figure 1.2, ... Has the problem beem solved?
Actually I am fine with figures by adding \numberwithin{figure}{section} to the Tex template, however, the same thing does not for listings.
@helenxu, if you're using non-standard pandoc LaTeX template (this includes the cases where document class is not article or close enough to that), pandoc-crossref can't do much with it. Configure LaTeX in the template appropriately.
Additionally, even when using the default LaTeX template with article document class, since pandoc-crossref offloads all numbering to LaTeX if it can, chapters: true has no effect on LaTeX output anyway. You have to specify Pandoc's --chapters option (in newer pandoc versions that has been changed to --top-level-division=chapter) -- which will configure the default LaTeX template appropriately. And you have to specify that for any output format actually, because pandoc-crossref can't signal pandoc you want to use chapters, and vice versa. I could swear this is all mentioned in the docs, but apparently not. I'll try to remember to fix that.
This all only relates to pandoc-crossref v0.3.x. v0.4.x (currently in alpha) works rather differently, and most notably, does not offload numbering to LaTeX.
Yes, I know this is all a bit of a mess, and that's one of the reasons v0.4.x tries to avoid treating LaTeX differently from other formats.
In case you're not really interested in LaTeX itself, and just want to produce a pdf, you might also consider using html or ms instead of latex as an intermediate format, as outlined in the pandoc manual.
@lierdakil Thank you so much for your patient explanation. I was trying to produce a book and latter I tried adding -top-level-division=chapter and -V book resolved my problem.
I am also having this problem and was wondering if something is broken or there is a minimal working example for within-chapter numbering behavior in LaTeX? I cannot duplicate it under any circumstances. I am now using a minimal document with a single top level header, one figure, one reference, and no metadata or special templating/document class. All three of the following commands produce identical results (e.g. references are getting populated, but figures are numbered Figure 1, Figure 2, etc. instead of Figure 1.1, Figure 1.2): pandoc test.md -o test.pdf --filter pandoc-crossref pandoc .\test.md -o test.pdf --filter pandoc-crossref --top-level-division=chapter pandoc .\test.md -o test.pdf --filter pandoc-crossref --top-level-division=chapter -V book
When I added \usepackage{listing} and \numberwithin{figure}{chapter} to the header-includes, I was able to get figure 0.1, 0.2, etc. numbering on the figure itself, but only when I turned off pandoc-crossref.
I get the same results using a version of pandoc-crossref, downloaded on April 9, 2020 as well as the newest full release, 0.3.6.3. What am I missing?
@eculler, you also need --number-sections in addition to --top-level-division=chapter to get by-section numbering in LaTeX. Which seems reasonable.