support older and newer versions of Pandoc

[agilly]

covrpage calls Pandoc to convert between formats. However, it seems to be tied to a narrow range of versions due to the options it uses.

• On version 1.19.2.4 it fails because pandoc: Unknown extension: gfm_auto_identifiers
• On the latest version 3.1.6 it fails because Unknown option --atx-headers.
• On the latest version before the switch to Pandoc 3 (2.19.2), it complains but proceeds:

[WARNING] Deprecated: --atx-headers. Use --markdown-headings=atx instead.  
[WARNING] Deprecated: markdown_github. Use gfm instead.  

This looks like it's caused by pandoc arguments changing with every version. Could it be feasible to extract the pandoc version using e.g. pandoc --version| head -1| cut -d' ' -f2 and adapting the options according to that?

[yonicd]

Thanks for opening the issue, I will look into this shortly.

[yonicd]

@cderv how would you go about this in Rmd?

[cderv]

Usually we do a conditional with rmarkdown::pandoc_available() to adapt depending on the version.
Example with --atx-headers: https://github.com/rstudio/rmarkdown/blob/0200cc36833579952ac469a78f8ac0610bcf1962/R/github_document.R#L83-L85
You need to decide how many version you want to support. And know if the feature you use enforce a minimum version.

1.19.2.4 is quite old and is a pre Pandoc 2.0 version. Lots of recent feature does not work with it for example.

How are you using Pandoc ? Are you calling Pandoc directly ? Are you using rmarkdown ?

[yonicd]

It’s just knitting an Rmd from ./inst (similar idea how reprex works)

[cderv]

Oh ok. So you should not deal with that yourself in covrpage - I see

covrpage/R/covrpage.R

Lines 44 to 50 in bafeb19

	rmarkdown::render(
	input = "tests/_covrpage.Rmd",
	output_file = "README.md",
	output_dir = "tests",
	output_format = "github_document",
	output_options = list(toc = TRUE, toc_depth = 3)
	)

So this is really about rmarkdown - we may need to update our conditional. Thanks for the report!

@agilly what is your rmarkdown version ? Are you using the latest ?

[cderv]

On version 1.19.2.4 it fails because pandoc: Unknown extension: gfm_auto_identifiers

Quite an old version - A lot of feature of rmarkdown won't work so the output could be quite different than with another version. Anyhow, we were missing a conditional for old version - added in rstudio/rmarkdown@ea9c7c9

On the latest version 3.1.6 it fails because Unknown option --atx-headers.

I don't know where this comes from. As linked before, we correctly only add --atx-headers when Pandoc version is below 2.11.2
https://github.com/rstudio/rmarkdown/blob/0200cc36833579952ac469a78f8ac0610bcf1962/R/github_document.R#L83-L85

[WARNING] Deprecated: --atx-headers. Use --markdown-headings=atx instead.

This should not be thrown for Pandoc 2.11.2 from the code shared just above

[WARNING] Deprecated: markdown_github. Use gfm instead.

markdown_github should only be use for Pandoc version before 2.0. https://github.com/rstudio/rmarkdown/blob/0200cc36833579952ac469a78f8ac0610bcf1962/R/github_document.R#L72-L78

So those warnings makes me think: Are you sure rmarkdown::render (hence covrpage is using the Pandoc version you are expecting it to use in each case ?

You should run rmarkdown::pandoc_version() to check which is the version used by covrpage for the rendering.

Also please, do confirm your rmarkdown version. If you have an old one, some conditional could be missing.

[yonicd]

is there any assertion i can add before running the render or is that redundant because it is done internally in rmarkdown anyway?

[cderv]

I would say it should be handled by rmarkdown. You don't activate any specific feature in pandoc_args. You are just calling github_document should it should be normal to expect that rmarkdown does the right think with Pandoc.

However, if you test several pandoc version, and notice that the rendering for what is inside your Rmd does not work or look great with old Pandoc, then you could have a minimal requirement. pandoc R package can help you test this.

But in rmarkdown we should handle any Pandoc version, and throw error or adapt depending on the pandoc version found, so you should not deal with that if your content does not depend on specific version IMO