Move the markdown package from Imports to Suggests

[yihui]

For package authors who use R Markdown vignettes based on the vignette engine knitr::knitr (or knitr::docco_linear, knitr::docco_classic, etc.), you should declare the (soft) dependency on markdown, e.g., in the package DESCRIPTION:

Suggests: markdown
VignetteBuilder: knitr

Previously they didn't need to do this because markdown has been a hard dependency of knitr (in Imports), so the availability of markdown is guaranteed by knitr, but I want to make markdown a soft dependency of knitr in the future.

I think most packages use the vignette engine knitr::rmarkdown to write vignettes now, but there may still be a few vignettes using the knitr::knitr engine, which depends on markdown. If I move markdown to Suggests in knitr, users have to make sure markdown is available to R CMD check. To achieve that, they have to add markdown to Suggests to their DESCRIPTION files.

Similarly, if your vignette is based on the vignette engine knitr::rmarkdown, you have to declare the dependency on rmarkdown, e.g.,

Suggests: rmarkdown
VignetteBuilder: knitr

The error message when building the source package via R CMD build should tell you if you need to add markdown or rmarkdown to Suggests, which looks like this:

* checking for file ‘PKG/DESCRIPTION’ ... OK
* preparing ‘PKG’:
* checking DESCRIPTION meta-information ... OK
* installing the package to build vignettes
* creating vignettes ... ERROR
--- re-building ‘doc.Rmd’ using rmarkdown_notangle
Error: processing vignette 'doc.Rmd' failed with diagnostics:
The 'rmarkdown' package should be declared as a dependency of
the 'PKG' package (e.g., in the  'Suggests' field of DESCRIPTION),
because the latter contains vignette(s) built with the 'rmarkdown'
package. Please see https://github.com/yihui/knitr/issues/1864
for more information.
--- failed re-building ‘doc.Rmd’

SUMMARY: processing the following file failed:
  ‘doc.Rmd’

Error: Vignette re-building failed.
Execution halted

If you are a package author affected by this issue, but not clear about what you need to do, please reply below and I'll be glad to help. I recommend that you skip the replies below. Thanks!

[tdhock]

hi I got this from win-builder:

* checking re-building of vignette outputs ... [1s] WARNING
Error(s) in re-building vignettes:
--- re-building 'examples.Rmd' using knitr
Error: processing vignette 'examples.Rmd' failed with diagnostics:
The 'markdown' package should be declared as a dependency of the 'directlabels' package (e.g., in the  'Suggests' field of DESCRIPTION), because it contains vignette(s) built with the 'markdown' package. Please see https://github.com/yihui/knitr/issues/1864 for more information.
--- failed re-building 'examples.Rmd'

SUMMARY: processing the following file failed:
  'examples.Rmd'

Error: Vignette re-building failed.
Execution halted

my vignette uses

%\VignetteEngine{knitr::knitr}

which I think does not require markdown (even in suggests), if I understand your discussion above correctly. so it seems strange that I would need to add markdown in suggests. do I really have to?

[yihui]

Yes, you have to.

[tdhock]

ok

[mschubert]

I think I'm getting a false positive warning on the CRAN Winbuilder. I've got all my vignettes set to

%\VignetteEngine{knitr::rmarkdown}

If I have not set in DESCRIPTION that

Suggests:
    rmarkdown

I'm getting no warnings locally (R=4.0.2, rmarkdown=2.2, knitr=1.28). On the CRAN Winbuilder, I'm getting:

Error: processing vignette 'quickstart.Rmd' failed with diagnostics:
The 'markdown' package should be declared as a dependency of the 'clustermq' package (e.g., in the 'Suggests' field of DESCRIPTION), because it contains vignette(s) built with the 'markdown' package. Please see #1864 for more information.

The missing package, however, is Suggests: rmarkdown and not markdown.

[yihui]

@mschubert I need a reproducible example. Could you provide a link to your package (presumably on Github?)? Thanks!

[mschubert]

Package was clustermq:3d223af and you can find the Winbuilder output here. I won't have time to track this down further unfortunately (since adding Suggests: rmarkdown solves the issue & a warning for the right package is there), sorry.

[yihui]

@mschubert In your case, you are using the vignette engine knitr::rmarkdown, so you have to add rmarkdown to Suggests (which you did mschubert/clustermq@02e06f8): https://yihui.org/knitr/demo/vignette/ Because you didn't do that, you saw the message about markdown, and that was because knitr fell back to using markdown to build your vignettes. Neither rmarkdown nor markdown was specified in your Suggests, and that's why you saw the error.

[mschubert]

Yes, that's what I tried to say - sorry if that was not clear. My comment was that the error message of "missing markdown package in Suggests" is confusing when the vignette states that it uses rmarkdown (and the markdown package should never be required).

Perhaps a better error message would be to add whatever markdown builder you use to Suggests? Or, maybe do nothing, but I thought it was useful to document that this message is also displayed when rmarkdown is missing (I guess people will google the issue and find this).

[yihui]

@mschubert Yes, I definitely agree the messages were confusing in this case. I'll think more about it and try to make it clearer. Thanks a lot for your feedback!

[nsheff]

I agree with @mschubert. I had the same situation. I was about to add 'markdown' to suggests because of the message, when I really should have added 'rmarkdown' to suggests, because I use knitr::rmarkdown (if I understood correctly).