More minimal YAML header

[eddelbuettel]

Persoanlly speaking, I really like the YAML to be minimal. There seem to be no way to "augment" the yaml data before rmarkdown::render() is called, so the best we can is to make the template.tex richer.

Things we could do:

• default font size (as 10pt in latex is not pretty); my suggestion would be 11pt
• default font choice, eg hardwire mathpazo
• default geometry margin (1in seems fine)
• zero indentation on the signature (as suggested below)
• maybe remove blockquote / make blockquote default too ?
• anything else?

I would be awesome to add per-user defaults (ie user Bob always want his bob_signature.pdf but that does not seem possible.

Thoughts, @aaronwolen ? This can of course also wait past the initial 0.0.1 release...

[aaronwolen]

My original inclination was to change pandoc-letter's default options to make the standard output a little nicer looking but ultimately decided to keep things in line with pandoc's latex template. I reasoned that would match user expectations and anyone capable of using a custom template would have no problem using the latex variables to define their own styles.

In this case, I think it does make sense to provide some nicer looking defaults and the ones your suggested all seem reasonable to me.

The one additional change I'd suggest is setting closing-indentation to 0—a centered signature always looks wrong to me...

[eddelbuettel]

Yes and yes and yes :) That'll all for 0.0.2 soon enough as I just shipped 0.0.1 to CRAN before a day of conferencing (about to start) so intermittent connectivity.

One idea I had, especially given your rather nice extensions on headers and signatures, is that a "fixed" template would be good. I.e. good "dry -- don't repeat yourself". I would love to not have to copy the same content from .Rmd to .Rmd. Alas, no free lunch. It seems rmarkdown::render() does not give us full access to the YAML front matter. So looking a bit more on the train in this morning I realized I really want .... and #include mechanism for YAML. Which from a casual reading of Google has been suggested but is outside of the YAML. Do you think we could / should lean on the YAML maintainer? Or am I crazy?

/cc to @jjallaire whom I already pestered with the same question re rmarkdown and includes.

[eddelbuettel]

One possible idea would be to just let the yaml package be yaml+ and allow an optional user-supplied addition entry.

[aaronwolen]

I would love to see include functionality added to the yaml package—there are so many use cases.

The Python package I use for home automation provides several options for including external YAML files, it's really convenient.

[eddelbuettel]

Awesome to have a reference for a working Python example. With that we may be able to lean on the yaml maintainer for R. Otherwise I had been thinking I would ... just have to wrap an outher layer around write the full yaml frontmatter (plus letter body). But getting it into yaml would be a winner. Let's work on that.

No word from CRAN yet.

[eddelbuettel]

Hm, I glanced at that. Is that a purely local yaml reader?

[eddelbuettel]

Updated first comment above reflecting #3.

[baptiste]

Curious to see where this idea goes. I have a related issue with journal articles and the formatting of affiliations etc. I'd like to include those in a separate per-project yaml file, but I could not find a way to include it via rmarkdown, as in:

----
output_format: pdf_document
metadata: `r process_headr("_metadata.yaml")`
----

and have the formatted preamble fragment injected into the article,

http://13.210.69.171:3838/sample-apps/apps/headr/

Essentially, use R to create templates on-the-fly, where pandoc's macro syntax is too limiting.

I wonder if knitr::pre_knit might help, but it's a little documented as the rest of the rmarkdown-knitr-pandoc toolchain.

[eddelbuettel]

@baptiste: I fear you can't. The yaml header is static as far as I know and cannot be expanded (unless you change yaml::yaml(), which is what we now suggested to @viking and his r-yaml). Also, there is very little expansion you can in the rmarkdown framework. So as best as @aaronwolen and I can tell is to "climb up one level" and generate the file, yaml header and body. (And thanks for #7 which I'll fold in.)

FWIW I already looked into this, every so briefly, for some of the earlier work @coatless and I did on pinp. All I could find then were some feature requests to rmarkdown by @ThierryO --- which only lead him to leave rmarkdown and go to the more featureful bookdown. Which seems like complete overkill for simple letters. Have yet to circle back with @ThierryO what his experience was, he seems to have nice (much richer) framework in IMBOmd (but it also aims much higher as far as I can tell).

[baptiste]

The yaml header is not completely static, though I find it hard to tell in what order the various processing steps occur, and when code might be evaluated.

I'm quite familiar with the standard template toolchain; for instance this is what I've developed for our seminars

For some reason, however, I seem to be the only one bothered by the pandoc macro syntax to create latex templates. It seems to me that Rmd, as a superset of md, has no real need for it; R pre-processing could replace those macros with much more powerful programming facilities, and a less awkward syntax.

[eddelbuettel]

It's a tradeoff. There is something to be said for staying with existing layers, which rmarkdown does by passing down to pandoc.

(And yes, I saw that SO post too, and found it unconvincing. We would need something earlier / different. But at this point I do not care about R computations in the yaml header, I just won't less "don't repeat yourself" (DRY) between files so pre-processing sounds good me right now.

[ThierryO]

@eddelbuettel : do you refer to rstudio/rmarkdown#1138? The main reason for the switch to bookdown only had to to with the ability to postprocess to tex file prior to rendering it to pdf. I don't think that is is issue here.

I have used the post_processor in INBOmd and rticles. I use it to read the tex file, modify it and write it before rendering to pdf. I assume the pre_knit works similar.

I think the post_knit is more likely the think you want to use to solve @baptiste suggestion.

[eddelbuettel]

@ThierryO Guess, that was thread I had found. Are you aware of anything for "earlier" in the flow, as for the possible !include issue @aaronwolen and I are after?

[ThierryO]

just a few idea's

• make all relevant parts available as a yaml variable
• have the user store their preferences in .Options
• use sensible details for things that the user didn't specify in .Options

[eddelbuettel]

The problem is that linl::linl() does not seem to be able to set the YAML metadata. I tried a few times.

Did I miss it?

But if that is the case, then .Options() or other tricks (rappdirs is ok too) is a no-go as it is "too late".

[ThierryO]

Have a look at rsos.R. Note that I didn't use inherit_pdf_document() but handle the YAML 'manually'

[aaronwolen]

@eddelbuettel, think the changes in #3–#9 are sufficient to close this issue and cut the next release?

We could save the proposed YAML preprocessor for v0.1.

[eddelbuettel]

I agree. Can we wait til, say, Sunday? It's been a week since we submitted, but not a week til it got there.

[aaronwolen]

Sure, that works. 👍

[eddelbuettel]

linl 0.0.2 is now on CRAN, with the smoothest possible transition form the [CRAN-pretest-publish] bot which let it in minutes after upload as previous version and current submission all scored OK.

The topics discussed here are reflected in it, so closing this.