Automated figure & table numbering

[dhimmel]

@slochower welcome to manubot-rootstock... which is meant to be forked when creating a new manuscript. Still a work in progress.

See previous discussions at greenelab/deep-review#354 (comment) and greenelab/deep-review#558.

It seems like the best way to number and reference tables and figures will be with pandoc-tablenos and pandoc-fignos, which are both python packages by @tomduck that we can add to the environment:

• https://github.com/tomduck/pandoc-tablenos
• https://github.com/tomduck/pandoc-fignos

They can be enabled in the pandoc conversion script with:

--filter pandoc-fignos
--filter pandoc-tablenos

Since we're also using jinja2 templating, we could do the conversion prior to pandoc if there is a compelling reason.

@slochower do you want to submit the PR? I'm thinking the initial use case we should target is markdown tables and figures embedded via absolute URL (let's save the relative image path case for later).

Also @slowchower, any idea how figure and table captions work?

CC @agitter.

[dhimmel]

@slowchower, we should also consider pandoc-crossref by @lierdakil. pandoc-crossref appears to be a more versatile numbering solution, supporting tables, figures, equations and more. The downside may be that it's harder to install in our conda environment, since I couldn't find a conda binary and it's not a python package.

[dhimmel]

One additional consideration is that we need LaTeX free solutions, as currently we export to HTML and PDF, but not using LaTeX.

[slochower]

@dhimmel Excellent; this looks fun. I'll take a look tomorrow and get back with some more information about this and #2.

[slochower]

It seems like the best way to number and reference tables and figures will be with pandoc-tablenos and pandoc-fignos, which are both python packages by @tomduck that we can add to the environment:

Right. These are mostly easy.

...we should also consider pandoc-crossref by @lierdakil

That looks nice. I feel like I stumbled across it at some point, but haven't used it. Maybe I should hold off on the PR while we evaluate this?

The downside may be that it's harder to install in our conda environment, since I couldn't find a conda binary and it's not a python package.

Do you mean for CI compilation? I think we can get a VM with GHC / cabal available. I don't remember what image the travis build is currently using.

One additional consideration is that we need LaTeX free solutions, as currently we export to HTML and PDF, but not using LaTeX.

Shouldn't be a problem. I used KaTeX to render some equations -- a javascript library that is LaTeX-free.

[dhimmel]

Do you mean for CI compilation? I think we can get a VM with GHC / cabal available. I don't remember what image the travis build is currently using.

Currently, any (linux) user can run:

conda env create --file environment.yml
source activate manubot

Voila, they will have everything needed to build the manuscript. It's nice to everything manageable within conda. If we go with pandoc-crossref, then we may have to switch to Docker for providing a consistent/portable environment. I think this adds a bit of overhead.

[slochower]

Ah, I see what you mean. Yeah, I agree that Docker is a bit much. (It still needs root to run, right?) Do you think porting the basic functionality from Haskell would be too hard? I'm guessing yes (and I don't know Haskell).

[dhimmel]

Do you think porting the basic functionality from Haskell would be too hard?

Yes, we're already maintaining too much with this project!

[agitter]

@dhimmel What are the main features provided by pandoc-crossref that aren't available with pandoc-tablenos, pandoc-fignos, and pandoc-eqnos? I have greatly appreciated being able to build the manuscript in an old Linux system that doesn't have Docker, so I support keeping everything managed within conda.

[dhimmel]

I have greatly appreciated being able to build the manuscript in an old Linux system that doesn't have Docker, so I support keeping everything managed within conda.

Agreed.

What are the main features provided by pandoc-crossref that aren't available with pandoc-tablenos, pandoc-fignos, and pandoc-eqnos?

Section references like so you could dynamically refer to / link section references. Not a huge deal. I think we should go with the simpler solution, as long as it works well.

[agitter]

Section references like so you could dynamically refer to / link section references.

I see. That did come up when we were writing deep review and had a hard time to referring back to previous sections.

[lierdakil]

FWIW, there are pre-built binaries on releases page, although due to dependency on Pandoc version this can get convoluted. Also those are provided with no warranty, as you might expect.

[dhimmel]

Closed by b03e1c3 and #8. Thanks @slochower!

[agitter]

Great! @dhimmel any thoughts on how we should merge this into deep review?

[dhimmel]

Great! @dhimmel any thoughts on how we should merge this into deep review?

Is there an immediate need for this in deep review? I think it makes most sense to delay merging into deep review until we knockout some more of the outstanding issues on this repo. I'm happy to do the merge, just let me know when. Still experimenting regarding the best ways to perform the merge.

[agitter]

It's not an immediate need. Two open pull requests - greenelab/deep-review#566 and greenelab/deep-review#567 - add a figure and table to deep review. However, I haven't even had time to review those so it is not at all urgent. We can continue to number manually until this repo stabilizes.