Allow to specify LaTeX dependencies in knitr_meta

[zeehio]

This patch allows third party packages to specify LaTeX package names and options to be inserted in the final LaTeX header.

Why is it needed

At least the condformat package needs to add \usepackage[table]{xcolor} to the .tex preamble. Currently the only way to do that is to add includes: in_header: filename in the yaml header of each of the files to be rendered. A package can not add by itself LaTeX dependencies.

Proposed solution

Based on the discussion started here, I wrote this patch. Summarizing:

• It exports a new function latex_dependency that can be used by the meta argument in knit_print as described here to add LaTeX package dependencies. A use case is found here.
• In the pdf_preprocessor, it compiles the dependency list and generates a .tex file that is added to the args passed to pandoc using includes_to_pandoc_args. The dependency list compilation is based on how it is done for the HTML dependencies.

Contributor agreement

• Just signed and emailed

Comments

• There is a github note in R/pdf_document.R asking for the best way to create a temp file in rmarkdown.

[zeehio]

Is there a specific rmarkdown way of creating a temporary file?

[jjallaire]

No there isn't anything special required here.

[jjallaire]

Could you add a NEWS item for this feature? Thanks!

[jjallaire]

@yihui This looks good to me, could you review as well?

[yihui]

You need to document this argument explicitly in roxygen instead of relying on @inheritParams html_document

[yihui]

This looks good overall. My only concern is that unlike HTML, LaTeX is so very fragile and this approach could easily fail, e.g. you cannot \usepackage twice on the same package with different options. Even you make sure you deduplicate these LaTeX dependencies, you may still have conflicts with packages that have already been used in the Pandoc LaTeX template. That is mainly an issue with LaTeX instead of this PR, so I'm fine with getting this PR merged later.

Another possibly useful feature is like the head argument of htmlDependency(), i.e. make it possible to write arbitrary LaTeX into the preamble (e.g. think \hypersetup{}), although this can make the system even more fragile.

[zeehio]

I have addressed all the code comments. Regarding @yihui comment about LaTeX fragility, I totally agree with you, but there is little I can do. Other packages that want to use this feature will have to cooperate in order to avoid compatibility issues.

Given that it seems all right to you, I would rather offer a simple initial implementation than trying to address all possible issues without having practical use cases.

[jjallaire]

@yihui Feel free to merge once you've reviewed all of the follow up commits.

[Auburngrads]

Something is unclear about this.

I'm building a package with a custom thesis template and want to include a custom .sty file in the pdf_document. My function, afit_thesis.R, contains a call to pdf_document in which I've provided the argument extra_dependencies=latex_dependency('myPackage') where 'myPackage' has been the name of the package and the path to the package using system.file. Various attempts have so far been unsuccessful.

After reading this pull request, the rmarkdown documentation and the online documentation for pdf documents, it is not clear as to where the custom Latex package should be stored or how it should be called to ensure it is included in a .tex file.

[yihui]

@Auburngrads Typically I just put them in a .tex file, and include the .tex file in the preamble via the includes option.

output:
  pdf_document:
    includes:
      in_header: your-preamble.tex

[Auburngrads]

@yihui By 'them' I assume you mean relative paths to the .sty files.

Per the documentation for includes() the path to the .tex file must be relative to input (.Rmd) document. For custom templates I believe that this also means that the .tex & .sty files must be included in the newly created template directory.

Perhaps my problem is trying to reference an absolute file path with system.file but I want to be sure that I can push updates to template.tex and myPackage.sty without requiring the user to move files from one directory to another.