Troubleshooting FAQ

Purpose: This document compliments Sweave2Rmd Contribute page. It is a FAQ inventory for common issues you may run into during the document conversion process. For more context on the project, see the Sweave2Rmd project page.

Common Questions:

Question: Can I Add a Footnote in the YAML title or author fields?

Answer: Ordinarily, footnotes are put inside the square brackets after a caret. e.g., ^[This is a footnote.]. However, due to a bug, footnotes in the YAML title or author fields no longer run. If attempted, you will receive a a LaTeX error. If you are converting a vignette and notice that the author byline includes a footnote, as does the Bioconductor vignette Random Numbers in BiocParallel, there is a work around. In the YAML, add three drop down lines for the author. Include all or a combination of the following: name, affiliation, and email. See below.

author:
  name: Martin Morgan
  affiliation: Roswell Park Cancer Institute, Buffalo, NY
  email: https://www.roswellpark.org/martin-morgan

Question: How can I handle duplicate chunk names?

Background info: When working with R markdown files, duplicate code chunk names tend to prevent knitting and may cause BiocCheck to fail.

Answer: Look for the exact duplicate code chunk names and rename them. For example if the duplicate code chunk name is example you can rename the other chunk name to example1 or example_ as long as it does not change the meaning or make it hard for someone to understand the code. If you do not understand the code or document well, always ask the maintainer or reviewers for what to do.

Question: Are you having trouble checking if R CMD build includes the HTML?

Background info: Sometimes, when converting a Sweave vignette to an R Markdown vignette, we may encounter issues while running R CMD build using the command tar ztf package_name.tar.gz | grep 'doc/vignette_name', even if the R CMD build command completes successfully without any errors or timeouts. This can happen if we have missed some essential lines in the YAML header or DESCRIPTION file.

Answer: To identify the problematic file, run tar ztf package_name.tar.gz | grep doc in your package terminal. If running the above command does not build the HTML file, try troubleshooting by removing your .Rmd file then running R CMD build and grepping the tarball for other vignettes. If other vignettes are built, the problem could be your .Rmd file. There are a couple of possible issues that could cause this problem. One possible issue might be that the %\VignetteEngine{knitr::rmarkdown} is missing from the YAML header. Another possible issue could be that VignetteBuilder: knitr is missing from the DESCRIPTION file. You can solve these issues by adding the missing lines in the correct format in their respective files. If you are unsure about the code or document, always ask the maintainer or reviewers for guidance.

Question: How can one handle the Unexpected end of document error when using tools like pandoc or Rnw2Rmd?

Background information: During the conversion process while running pandoc or Rnw2Rmd,
an “unexpected end of document” error prevents the .Rmd file from being created. For example, the error message states:

Error at "C:/Users/path.Rnw" (line 554,column 2):
unexpected end of document
^

Answer: The unexpected end of document error typically arises when certain code chunks contain special characters. To identify the problematic code chunk, it is advisable to remove the code chunks one by one from the .Rnw file and attempt to run the code. This approach allows you to pinpoint the specific code chunk causing the issue. Once the problematic code chunk has been identified, it should be removed. After successfully generating the .Rmd file, the problematic code chunk can then be included in the .Rmd file using Rmarkdown format. If you are unsure about the code or document, always ask the maintainer or reviewers for guidance.