---
title: "Rmd on Rmd"
author: "Paul E. Johnson"
output: slidy_presentation
---

# Document Structure Overview

## YAML Header

<b>YAML</b> = Yet Another Markdown Language

- A set of text declarations that govern a post-processing program
- Bare minimum is
<pre>
---
title: "Rmd on Rmd"
---
</pre>

- for presentations, the designation 
<pre>
output: slidy_presentation
</pre>
slidy_presentation is convenient, but not strictly necessary.  Selector could be included in a script that does post-processing instead.

## Style following that

- It is very flexible design (in practice, made less flexible by assumptions about "most" users)
- Some seemingly obvious details are not yet attended to (must be patient)
- markdown style & instructions vary grossly across authors because of different output destination.
- user can directly write any HTML desired into a presentation intended for HTML output, but same not necessarily compatible with other output formats.

## Style guides & tipsheets

- write more in
Pandoc markdown: <a href="http://rmarkdown.rstudio.com/authoring_pandoc_markdown.html">http://rmarkdown.rstudio.com/authoring_pandoc_markdown.html</a>

Daring Fireball: <a "http://daringfireball.net/projects/markdown/syntax">http://daringfireball.net/projects/markdown/syntax</a>

RStudio Docs: <a "https://support.rstudio.com/hc/en-us/articles/200486468-Authoring-R-Presentations">https://support.rstudio.com/hc/en-us/articles/200486468-Authoring-R-Presentations</a>

# Converting documents to outputs

## Understand the process {.allowframebreaks}

- If there were no R involved, this is what would happen.

1. User writes document in markdown, calls file "mgp.md" (my great presentation)

2. A program, currently <b>pandoc</b>, is used to convert the document the user prepared into HTML, PDF, and so forth. 
     1. Make an html slideshow in S5 format
<pre>
pandoc -t S5 mpg.md -o mgp.html
</pre>
    2 . Make a PDF slideshow in beamer format
<pre>
pandoc -t beamer mgp.md -V theme:Warsaw -o mgp.pdf
</pre>

See <a href="http://johnmacfarlane.net/pandoc/demo/example9/producing-slide-shows-with-pandoc.html">Producing slide shows with Pandoc</a> by John Macfarlane, who has been a key contributor in the markdown movement. 

3. I tested many output formats in Ubuntu 14.10.  Many formats available that are interesting, not all work well with my example document (more on that below)

## Important take away point: Limitations

- pandoc includes routines to convert just about anything to just about anything else.  
- That does not imply that anything can be turned into a nice version in any other format.
    + Works very well when the programmer's idea of what should go into which format matches the user's idea.
    + Expect trouble if you prepare something to go into HTML and then try to put same into PDF, bad outcomes. 
- Many parts of markdown syntax are <i>specific</i> to the document type.
    + slide markdown different from article markdown.  (That's a problem.)

## Now introduce R complication

- User wants to insert code chunks in a file
<pre><code>
 ` ` `{r option-option-option}
 rcode here
 ` ` `
</code></pre>

That fills the same role as the Sweave chunk style.  
<pre>
<<option-option-option>>=
rcode here
@
</pre>
- Honestly, I don't understand why the markdown people didn't keep the same style

## render equals knit + pandoc

1. knit: convert Rmd to md
    The markdown file is run and the code chunks are--literally--replaced with R input and output.

    - Can be done in various ways. Most direct

        1 <pre>R CMD knit mgp.Rmd</pre>

        2 <pre>R -e "library(knitr); knit(\"mgp.Rmd\")"</pre>
        
2. pandoc: convert the new md into HTML or PDF or whatnot

## Do both steps at once

- Rmarkdown package
<pre><code>
R -e "library(rmarkdown); render(\"mgp.Rmd\")"
</code></p>
- RStudio creates a little confusion in terminology by using word "knit" in their GUI. Should be "render".  Read help for Rmarkdown package and the <code>render</code> function.  The RStudio documents on what is going on, they are putting their own spin on it.  

## Tidbits about render

- Hides & erases the intermediate files (optionally)
- The "all in one" HTML document format.
    - Codes images and such into MIME format, so they appear as text in the html document itself
    - Same used in <a href="http://pj.freefaculty.org/R/WorkingExamples">http://pj.freefaculty.org/R/WorkingExamples</a>

# Working around gotchas

## Can't resize images that are imported with markdown

- Stop using markdown to import the image, use true HTML img tags. 

```
<img src="importfigs/Fumble-Chart-1.png" width="700" alt="Fumbles">
```

- images are stored in a folder importfigs, here's going to be
an image that is 700 wide on next page.

## Chart asserting Patriots are Cheaters
<img src="importfigs/Fumble-Chart-1.png" width="700" alt="Fumbles">

- Warren Sharp, "The New England Patriots Prevention of Fumbles is
  Nearly Impossible", http://www.sharpfootballanalysis.com/blog/2015/the-new-england-patriots-prevention-of-fumbles-is-nearly-impossible

## slides too long for page

- The slide argument {.allowframebreaks} is based on the LaTeX Beamer
argument, it is intended to solve this problem

- However the ioslides_presentation converter in pandoc does not
respect .allowframebreaks, which is a crushing disappointment.

- The slidy_presentation is not quite so polished as ioslides, but it
  DOES respect .allowframebrakes. I used one in the "Understand the
  Process Slide Above".

## code lines too long

- can have knitr call formatR to reformat code with line wrapping.

- Since formatR fails on about 25% of the code examples I run through
  it, this is not a perfect solution. 

- Manipulate the R output. In R, run this at the start of the session
```
options(width = 70)
```
to keep line output shorter. This solution works dependably.

## Cannot have R code chunk in 2 column format

Apparently unsolveable problem.

## I hate double pound signs in output

Can be removed. It is discussed here
http://stackoverflow.com/questions/15081212/remove-hashes-in-r-output-from-rmarkdown-and-knitr

- I confirm on next slide that does work one slide at a time

- Have not found document-wide solution yet.  Person there asserts
  this will erase the point signs, opts_chunk$set(comment = NA), but I
  don't know where how to use that


## Lets test that {.allowframebreaks}
```{r comment = NA}
dat <- data.frame(x1 = rnorm(100), y1 = rnorm(100))
print(dat)
```

## I want to save the fig files and insert them in my document {.allowframebreaks}

- This is a LaTeX strongpoint that I find lacking in the markdown approach.

- Sweave has a "split" feature where we can drop all the
generated figures and LaTeX output into a folder, and then later
insert those things when we want them.

- Especially since 2 columns does not tolerate R code embedded, such a
  feature would be especially helpful

- Also, I want to insert same figures into a writeup.

- Very difficult to un-do the cleanup effort of render here.

    - I will eventually wade through the layers of simplifications and
user interface "enhancements", but it is really frustrating

