[FR] - Update the variant parameter documentation for md_document

[briandk]

The Problem

It looks like the documentation for an md_document's markdown variant has fallen out of step with the actual implementation. If we compare the documented parameters to the ones in the current source code as of this writing, it looks like the undocumented options are commonmark and commonmark_x:

In the book	In the source code
markdown	gfm
markdown_strict	commonmark
markdown_github	commonmark_x
markdown_mmd	markdown
markdown_phpextra	markdown_phpextra
	markdown_github
	markdown_strict

This discrepancy leads me to a few questions.

1. Is commonmark_x meant to be something user-facing?
2. Should there be an rmarkdown variant?

I know question 2 might seem silly: your source file is Rmarkdown, so why would you want to specify the output as Rmarkdown? But, it would be nice to have one variant that represents all the markdown extensions that Rmarkdown uses, so I wouldn't have to manually specify them if I want to make a clean plaintext export.

Example Use Case

I'm writing a manuscript in Rmarkdown. I'm currently using the RMarkdown Visual Editor with sentence-level line wrapping. The result is a manuscript where single paragraphs are broken across multiple lines. This line wrapping is great for fine-grained version control to track changes, but it doesn't look nice to read.

What I'd love is an easy way to specify turning this document into an Rmarkdown document that wraps at the paragraph-level.

Thanks!

[cderv]

Hi @briandk !

Thanks for spotting that. We have improve support for more markdown variants as Pandoc has evolved. The documentation of md_document (https://pkgs.rstudio.com/rmarkdown/reference/md_document.html) is up to date, but we haven't updated the book ! We'll do that.

Is commonmark_x meant to be something user-facing?

commonmark_x is one of the markdown variant supported by Pandoc. So if a user wants to produce such document, it is possible using variant parameter.

Should there be an rmarkdown variant?

The variant refers to the Pandoc's markdown variants as mentioned in the help page of the function. rmarkdown is not one of them. A R Markdown document uses Pandoc's markdown syntax + other special feature added by the R Markdown package. Also I would not know what rmarkdown variant would mean, and it would not be in the same category as the other ones any way (as not a Pandoc's supported variant). So I wouldn't use this solution to solve your problem. Maybe we can find something else.

Regarding the visual editor, I know it will modify the source for you according to the settings chosen, this line wrapping is one of them. The editor will produce a document with clean and clear markup following this option. I believe the wrap: sentence option is there for version control tracking indeed, and the editor is there for nice reading with unwrapped line. I understand you want to post process the document to unwrap the source code, is that right ?

If you want to re-style the markdown document, maybe using the --wrap option in Pandoc would help change this wrapping (https://pandoc.org/MANUAL.html#option--wrap). By default, it should already wrap at columns length, so doing something like rmarkdown::render("test.Rmd", rmarkdown::md_document("markdown", preserve_yaml = TRUE)) would produce a .md file with another line wrapping. However, I don't think it would play well with knitr code chunk and Pandoc does not know about them. They would need to be protected.

Maybe using a styling tool can help to read the line and wrap them at column length. However, I am not sure styler supports line length and formatR does not know how to handle Rmd file (yihui/formatR#72)

This is an interesting request, but quite specific. Conversion from Rmarkdown to Rmarkdown is not common I think.
I believe this would rather be something for a styling tool (like formatR) instead of a specific algorithm to undo the algorithm from the Visual editor, as this concerns mainly line wrapping as I understand.