[Organization] Define plugin functions

[fmoralesc]

Just from the top of my mind:

• We need a special make command that calls rmarkdown instead of vanilla pandoc.
  • Implement the command execution
  • rmarkdown has a lot of options so a nice vim command user interface like the one provided for pandoc will be desirable.
• We need to specialize the syntax to highlight R code blocks by default.
  • Implement RMarkdown's syntax for code chunks.
  • Each chunk header could set a number of chunk options so highlighting the correct ones could be of some help detecting errors.

[fmoralesc]

Shouldn't R -e 'rmarkdown:render(...) be enough? Is knitr necessary?

[memeplex]

Knitr is the literate programming preprocessor. It replaces the r chunks
with their output. Rmarkdown is, since its latest version, more of a pandoc
wrapper. Afaik it has no direct support for knitr, instead it's the other
way around.
On Jul 12, 2014 4:52 PM, "Felipe Morales" [email protected] wrote:

Shouldn't R -e 'rmarkdown:render(...) be enough? Is knitr necessary?

—
Reply to this email directly or view it on GitHub
#1 (comment)
.

[fmoralesc]

Ah, I see. I was testing using rmarkdown directly, and it seemed to work fine.

[fmoralesc]

Maybe we should support both pipelines?

[memeplex]

It seems that in the latest version rmarkdown::render is indeed taking care of calling knitr as you suggested. I guess they are doing it the way they are because they've taken a more organic point of view which embraces, besides other tools, shiny, which generates dynamic html plots from r chunks. This is an effort from the rstudio team that includes the new version of rmarkdown, shiny, and their IDE support for them. Instead, knitr predates this integration effort. It's just an educated guess of mine but I think we should support only one pipeline, people is using this toolset for generating reports that include plots (interactive or static), code and its textual or tabulated ouput, and formatted text in general. From the Rendering Output section in http://rmarkdown.rstudio.com I infer rmarkdown::render is all we need. The previous pipeline knitr -> rmarkdown (was sundown) -> html looks more like rmarkdown -> (pandoc, knitr, shiny) now.

I will do some research regarding the new api and let you know about parameters and the like. Presumably render will take lot of parameters to customize both knitr and pandoc.

[fmoralesc]

Yes, I'm not really groking how knitr is supposed to work. By default, kniting a .Rmd file creates a markdown file that describes more or less what the output of rmarkdown::render() would be. knit('input.Rmd', output='input.html') does the same, but simply changes the extension. Is this supposed to be in turn processed by pandoc? Seems cumbersome.

So yes, I think using rmarkdown::render() is the way to go.

[memeplex]

I think rmarkdown is just conducting the orchestra. It's putting a lot of configuration under the hood, making shiny available to the R chunks, offering a number of predefined output formats in a simple way... Considering the difficulty to find the technical documentation (I got it from R shell itself, it doesn't seem to be available in the web yet) I have the feeling that the Rstudio team is all for a convention over configuration approach. Besides that, they've added yaml headers to tinker with the options at the document level, in case it's needed. Maybe they're right, the use cases are pretty well defined and they're providing simple specific interfaces to complex generic tools, albeit with space for further customization. All in all, I conclude that there is no need to provide a complex make command with lots of options, autocompletion, etc. A custom option would be ok, maybe a vimscript function that returns the command to be invoked, defaulting to rmarkdown::render().

Regarding the syntax highlighting part, highlighting of correct yaml properties and values could be worthy. I'll gather a list for you.

[memeplex]

The doc for the render function:

Usage

render(input, output_format = NULL, output_file = NULL, output_dir = NULL,
       output_options = NULL, intermediates_dir = NULL,
       runtime = c("auto", "static", "shiny"),
       clean = TRUE, envir = parent.frame(), quiet = FALSE,
       encoding = getOption("encoding"))
Arguments

input   
Input file (R script, Rmd, or plain markdown).

output_format   
R Markdown output format to convert to. Pass "all" to render all formats defined within the file. Pass the name of a format (e.g. "html_document") to render a single format or pass a vector of format names to render multiple formats. Alternatively you can pass an output format object; e.g. html_document(). If NULL is passed then the output format is the first one defined in the YAML metadata of the input file (defaulting to HTML if none is specified).

output_options  
List of output options that can override the options specified in metadata (e.g. could be used to force self_contained or mathjax = "local"). Note that this is only valid when the output format is read from metadata (i.e. not a custom format object passed to output_format).

output_file 
Output file. If NULL then a default based on the name of the input file is chosen.

output_dir  
Output directory. An alternate directory to write the output file to (defaults to the directory of the input file).

intermediates_dir   
Intermediate files directory. If NULL, intermediate files are written to the same directory as the input file; otherwis.

runtime 
The runtime target for rendering. static produces output intended for static files; shiny produces output suitable for use in a Shiny document (see run). The default, auto, allows the runtime target specified in the YAML metadata to take precedence, and renders for a static runtime target otherwise.

clean   
TRUE to clean intermediate files created during rendering.

envir   
The environment in which the code chunks are to be evaluated during knitting (can use new.env() to guarantee an empty new environment).

quiet   
TRUE to supress printing of the pandoc command line.

encoding    
The encoding of the input file; see file.

[fmoralesc]

OK. I think for now it's best to simply provide the rmarkdown pipeline, which is also more similar to pandoc's (basically the same). Our API should cover at least the options for render(). I'll leave further discussion for the other thread about this: #2

Thanks for the info.

[memeplex]

Also, take a look at
http://rmarkdown.rstudio.com/html_document_format.html. They talk a lot about yaml headers but never mention that render could be called as, say, render("input.Rmd", html_document(toc = TRUE)). Now, html_document takes an overwhelming amount of options:

html_document(toc = FALSE, toc_depth = 3, number_sections = FALSE,
  fig_width = 7, fig_height = 5, fig_retina = 2, fig_caption = FALSE,
  smart = TRUE, self_contained = TRUE, theme = "default",
  highlight = "default", mathjax = "default", template = "default",
  css = NULL, includes = NULL, keep_md = FALSE, lib_dir = NULL,
  pandoc_args = NULL, ...)

I don't think we should deal with this complexity. The user can tweak configuration at the yaml level. Maybe the output file, format, dir, etc, paramters to render could be exposed from a command interface, in a way consistent with the rest of vim-pandoc, but I wouldn't go further than that. If the user does want to produce his own render invocation, he must build the complete string to be invoked.

[fmoralesc]

Hm. What about this interface:

:RMarkdown html -quiet toc=FALSE, theme="default"

This should become

rmarkdown::render(..., html_document(toc=FALSE, theme="default"), quiet=TRUE)

We could parse the commandline so arg[0] defines the filetype, arguments starting with - are passed as arguments to render() itself and the rest of the arguments are passed to the output type object (html_document()in this case). We shouldn't worry about passing wrong arguments, it would be enough to let rmarkdown fail and notify us of the problem. Command completion should only return output formats.

[memeplex]

Looks great to me but I feel that you are the right person to decide about
that.

Btw, I will be travelling tonight so I won't be available online till
tomorrow.

On Sat, Jul 12, 2014 at 6:28 PM, Felipe Morales [email protected]
wrote:

Hm. What about this interface:

:RMarkdown html -quiet toc=FALSE, theme=default

This should become

rmarkdown::render(..., html_document(toc=FALSE, theme="default", quiet=TRUE)

We could parse the commandline so arg[0] defines the filetype, arguments
starting with - are passed as arguments to render() itself and the rest
of the arguments are passed to the output type object (html_document()in
this case). We shouldn't worry about passing wrong arguments, it would be
enough to let rmarkdown fail and notify us of the problem. Command
completion should only return output formats.

—
Reply to this email directly or view it on GitHub
#1 (comment)
.

[fmoralesc]

Since it's you who is going to use this, I wanted to know what looks right. ;)

I might travel tomorrow, so I won't be available for a few days. I'll try to make a functional prototype of what we've discussed tonight.

[fmoralesc]

I've implemented the :RMarkdown command as described above, more or less. To ease up command parsing, I adopted the convention that rmarkdown::render() arguments should be enclosed in - and -, so for example, to pass arguments to it and some output object, you should use

:RMarkdown pdf - quiet=FALSE - latex_engine="lualatex", -toc=TRUE

Commas are required between arguments.

If some error happens, the output of Rscript is shown in a nofile buffer, like in vim-pandoc.