Consider making slidify pandoc-compatible

[ramnathv]

Consider making slidify pandoc-compatible

[ramnathv]

On a related note, there seem to be multiple approaches taken to separating slides in a markdown document

1. Most of the ruby based tools like showoff, keydown etc. seem to use !SLIDE foo bar to define a slide with class = "foo bar". Users can wrap the specification as <!SLIDE foo bar> so that the markdown document is rendered neatly, even as just a page. showoff has an extra feature thrown in that uses all <h1> tags as slide delimiters if it does not find any !SLIDE specification.
2. In the python world tools like landslide and hieroglyph seem to prefer --- as slide separator and using reSt directives to specify slide classes and transitions.

I need to think more about the pros and cons of each approach, and what I would like to use for slidify. It might be a nice idea to do a survey on what people think about these options, and if it is important at all.

I personally like the <!SLIDE foo bar #id> idea since it is clean and allows easy parsing of slide classes and content. The only problem is that it might be cumbersome to write, over --- which is easy.

[ramnathv]

Right now, I have implemented the following.

1. Preferred way to separate slides is to use !SLIDE foo bar or <!SLIDE foo bar>
2. If no !SLIDE tag is found, a helper function searches for --- and replaces it with !SLIDE before slidification.
3. If neither !SLIDE nor --- are found, then a helper function adds !SLIDE before ever ### heading.

I need to make this customizable, since different html frameworks use different default levels for slide titles.

[ramnathv]

It would be easy to achieve this within the current design framework I am using. The key is determining the slide_header_level, which determines how the document is split into slides.

1. Headers at the slide level always start a new slide.
2. Headers below the slide level create headers within a slide.
3. Headers above the slide level create title slides.

I can easily factor this by modifying the code for add_slide_separator as

add_slide_separator <- function(doc, slide_header_level){
  n = slide_header_level
  if (any(grep('^---', doc))){
    doc = gsub("^---", "!SLIDE", doc)
  } else {
    doc = gsub("^(#{n,}.*)$ ", "<!SLIDE>\n\\1", doc)
  }
  return(doc)
}

The trick will be to determine the slide_header_level using a good heuristic that is consistent

[ramnathv]

I have made more pandoc compatible changes for supporting incremental slides. So the incremental list

> - point 1
> - point 2

will be rendered as an incremental list. The same idea works for ordered lists too.

[chiphogg]

First off...

(Disclaimer: I've immersed myself in a ton of new concepts lately: markdown, pandoc, knitr, various html5 slide solutions. It's a little disorienting to process all of this mentally -- so I may be off the mark here or misunderstand something basic.)

Anyway:

It seems to me the pandoc style is more amenable to hierarchical/outline-style organization, i.e., using sections and subsections. If only --- delimits slides -- as I believe is currently the case with slidify -- the resulting document has too "flat" a structure.

Ideally, I would like to structure the presentation using mainly section headers, e.g.,

# First section

## Slide title

This slide has a little content

## Another slide

Lots of content on this one...

---

...so I don't mind breaking it up manually.

with horizontal rules only used to break up too-long slides.

This also lets me take advantage of vim's folding for markdown/pandoc documents, which makes navigating my presentation source code a breeze.

[ramnathv]

Implementing pandoc style within the current framework is simple as it just requires adding slide separators based on the outline. I have a simple utility function that does that.

The reason I made slide separators an inherent part of the design of slidify is to use the power of templates and slide metadata which make it easy to define different layouts and smoothly create slides as if you were using powerpoint. I haven't documented this feature much, but once I do, you will notice the amount of power it provides.

[ramnathv]

I have achieved a reasonable level of compatibility with Pandoc. By making slide separators explicit, I can do a lot more than what Pandoc can achieve. So, I am closing this issue.

[chiphogg]

Not just more; also less. Specifically: you cannot make slides from a simple hierarchical document without including explicit separators.

We seem to have a deep and persistent design disagreement about whether this is valuable. That's fine; I respect your design decisions and I think slidify is overall excellent. I have used it very successfully in the past and will continue to do so. Thanks again for the highly useful package, and keep up the good work!

[ramnathv]

I agree that not having to use explicit separators would be beneficial especially when you are making text based slides with a linear flow (bullet-point style). I did some preliminary work on this, where you could specify a slide header level, say 2, in which case all h2 level headers act as slide separators. The easiest way to achieve this was by automatically adding the slide separator \n\n--- before slidifying the deck. I ran into two issues.

1. The splitting has to be done prior to transforming to html. It was easy to detect ## style headers, but --- style headers are more difficult to detect. Maybe, I can add support just for ### style.
2. The algorithm had to make sure that separators are not added before comments inside the code chunks, which would then require bookkeeping.

I would be happy if someone can send me a pull request on this one. Essentially, I need a function that will take the text of the Rmd document, a slide header level and automatically add slide separators. Once I have this, it would be straightforward to add this feature.

If there are other pandoc features you miss, post them here and I will see what can be done.

[chiphogg]

Thanks for sharing your previous work!

I would love to implement this, but when I look honestly at all the projects on my plate, I don't see myself getting to it in the near term. I will put it on my "Someday/Maybe" list, but anybody else who finds value in this can feel free to tackle it in the meantime.

At this time I can't think of any other pandoc features I'm missing in slidify.

[1beb]

I wonder if something as simple as this could work:

txt <- readLines(con="path/to/slidifyDemo/index.Rmd")
txt <- gsub("##","---\n##",txt) # Re-add
write(txt,"path/to/slidifyDemo/index.rmd") # Write file again, \n is converted to proper carriage return.

Nope, if people use ## in a comment block, this could break it.

[ramnathv]

That was my problem too. It is not difficult to trace code blocks and exclude them from the gsub, but might need some book keeping.

[ramnathv]

This should do the trick

find_code_lines <- function(doc){
  code_blocks = which(grepl("^```", doc))
  code_lines = NULL
  for (i in seq.int(1, length(code_blocks), by = 2)){
    code_lines = c(code_lines, code_blocks[i]:code_blocks[i + 1])
  }
  return(code_lines)
}

add_slide_separator <- function(deckFile, slide_header = "###"){
  doc <- readLines(deckFile)
  code_lines = find_code_lines(doc)
  pattern = paste0('^(', slide_header, ".*)")
  doc[-c(code_lines)] = gsub(pattern, '\n---\n\\1', doc[-c(code_lines)])
  writeLines(doc, con = deckFile)
}

I have done limited tests and it seems to be working. I would appreciate if either of you could test it on some decks and let me know if it is robust enough. Once I am convinced, it should be easy to add this as a wrapper into Slidify.

UPDATE: This will not fix the Rmd file, since it is the source. Instead, it will run on the md file created before it is passed off to the slidify functions to render to HTML. More specifically, it will apply here

deckFile <- ifelse(knit_deck, knit(inputFile, outputFile), inputFile)
post <- deckFile %|% add_slide_separator %|% parse_deck

[bbolker]

+1 for working this out. I hope to get a chance to try it out soon. (I'm hoping I can achieve pandoc compatibility so that I can use pandoc's bibliography support and for the ability to translate the same base document to LaTeX (for tufte-class handouts of the same document).

[ramnathv]

Let me know how it goes. I am thinking how slidify can use latex templates as well so that the same slide deck or document can be rendered bit as html and pdf, retaining nuances like two column layouts.

[1beb]

That would be great, right now I'm relying on Google Chrome for printing to PDF (from IO2012 style)

[ramnathv]

I am also in the process of putting together a script that would automate print to pdf like Chrome.

[1beb]

What language are you writing the script in?

[ramnathv]

Here is a gist https://gist.github.com/ramnathv/b1ff25adcccebfdd44d6.

I am using casperjs and a makefile. The makefile in the example is specific to a particular directory structure and will have to be tweaked. When I have a generic solution, I will try to package it with slidify.

Let me know if you have more questions.