From 1dab5e40346704ed28976dba3ed61ec0d9f95fd7 Mon Sep 17 00:00:00 2001
From: Carson Sievert <cpsievert1@gmail.com>
Date: Wed, 6 Jun 2018 11:12:04 -0500
Subject: [PATCH 1/7] add note about new automargin default

---
 NEWS.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/NEWS.md b/NEWS.md
index 7f3dfeccf8..3a8c19d527 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -22,7 +22,7 @@
 * The `plot_geo()` function gains a `offline` argument for rendering `"scattergeo"` traces with or without an internet connection (#356). Leveraging this argument requires the new **plotlyGeoAssets** package.
 * Instead of an error, `ggplotly(NULL, "message")` and `plotly_build(NULL, "message")` now returns `htmltools::div("message")`, making it easier to relay messages in shiny when data isn't yet ready to plot (#1116).
 * The `animation_button()` function gains a `label` argument, making it easier to control the label of an animation button generated through the `frame` API (#1205).
-* Support for async rendering of inside **shiny** apps using the [promises](https://rstudio.github.io/promises/) package (#1209).
+* Support for async rendering of inside **shiny** apps using the [promises](https://rstudio.github.io/promises/) package (#1209). For an example, run `plotly_example("shiny", "async")`.
 
 ## CHANGES
 
@@ -36,6 +36,7 @@
 
 ### Other changes relevant for all **plotly** objects
 
+* All axis objects now default to `automargin = TRUE`. The majority of the time this should make axis labels more readable, but may have un-intended consequences in some rare cases (#1252). 
 * The `elementId` field is no longer populated, which fixes the "Ignoring explicitly provided widget ID" warning in shiny applications (#985).
 
 ## BUG FIXES

From 33d7e68b085a2a0c6394a93426474091450bc62e Mon Sep 17 00:00:00 2001
From: Carson Sievert <cpsievert1@gmail.com>
Date: Wed, 6 Jun 2018 17:01:32 -0500
Subject: [PATCH 2/7] Add mathjax support via cdn

---
 R/layout.R                          |  9 ++++++-
 R/mathjax.R                         | 40 +++++++++++++++++++++++++++++
 R/orca.R                            | 16 ------------
 inst/htmlwidgets/lib/mathjax/cdn.js |  4 +++
 4 files changed, 52 insertions(+), 17 deletions(-)
 create mode 100644 R/mathjax.R
 create mode 100644 inst/htmlwidgets/lib/mathjax/cdn.js

diff --git a/R/layout.R b/R/layout.R
index 98eb8ac7ac..b6a3c74d05 100644
--- a/R/layout.R
+++ b/R/layout.R
@@ -117,7 +117,7 @@ rangeslider <- function(p, start = NULL, end = NULL, ...) {
 #' config(p, locale = "zh-CN")
 #' 
 
-config <- function(p, ..., collaborate = TRUE, cloud = FALSE, locale = NULL) {
+config <- function(p, ..., collaborate = TRUE, cloud = FALSE, locale = NULL, mathjax = FALSE) {
   
   if (!is.null(locale)) {
     p$dependencies <- c(
@@ -127,6 +127,13 @@ config <- function(p, ..., collaborate = TRUE, cloud = FALSE, locale = NULL) {
     p$x$config$locale <- locale
   }
   
+  if (!identical(mathjax, FALSE)) {
+    p$dependencies <- c(
+      list(mathjax_dependency()),
+      p$dependencies
+    )
+  }
+  
   p$x$config <- modify_list(p$x$config, list(...))
   
   nms <- sapply(p$x$config[["modeBarButtonsToAdd"]], "[[", "name")
diff --git a/R/mathjax.R b/R/mathjax.R
new file mode 100644
index 0000000000..05af3885d5
--- /dev/null
+++ b/R/mathjax.R
@@ -0,0 +1,40 @@
+mathjax_cdn <- function() {
+  htmltools::htmlDependency(
+    name = "mathjax",
+    version = "2.7.4",
+    src = c(file = depPath("mathjax")),
+    script = "cdn.js"
+  )
+}
+
+# TODO: wait until there is a more official way to include query parameters
+# https://github.com/rstudio/htmltools/issues/98
+mathjax_local <- function() {
+  htmltools::htmlDependency(
+    name = "mathjax",
+    version = "2.7.4",
+    src = c(file = mathjax_path()),
+    script = "MathJax.js?config=TeX-AMS-MML_SVG"
+  )
+}
+
+
+mathjax_path <- function() {
+  path <- Sys.getenv("PLOTLY_MATHJAX_PATH", NA)
+  if (!is.na(path)) {
+    mj <- file.path(path, "MathJax.js")
+    if (!file.exists(mj)) stop("Couldn't find 'MathJax.js' file in local directory")
+    return(path)
+  }
+  
+  if (system.file(package = "rmarkdown") != "") {
+    # Note, this should throw an informative error if the path isn't found
+    return(getFromNamespace("pandoc_mathjax_local_path", "rmarkdown")())
+  } 
+  
+  stop(
+    "To use a local version of MathJax with plotly, either set the PLOTLY_MATHJAX_PATH",
+    "environment variable to the location of MathJax or install rmarkdown.",
+    call. = FALSE
+  )
+}
diff --git a/R/orca.R b/R/orca.R
index 104e6aa60c..415e1ce97c 100644
--- a/R/orca.R
+++ b/R/orca.R
@@ -71,19 +71,3 @@ orca <- function(p, file = "plot.png", format = tools::file_ext(file),
   try_library("processx", "orca")
   invisible(processx::run("orca", args, echo = TRUE, spinner = TRUE))
 }
-
-
-mathjax_path <- function() {
-  if (is_rstudio()) {
-    try_library("rmarkdown", "orca")
-    return(getFromNamespace("pandoc_mathjax_local_path", "rmarkdown")())
-  }
-  path <- Sys.getenv("PLOTLY_MATHJAX_PATH", Sys.getenv("RMARKDOWN_MATHJAX_PATH", NA))
-  if (!is.na(path)) return(normalizePath(path, mustWork = TRUE))
-  stop(
-    "Please set either the RMARKDOWN_MATHJAX_PATH or PLOTLY_MATHJAX_PATH ",
-    "environment variable to the location of MathJax. ",
-    "On Linux systems you can also install MathJax using your system package manager.",
-    call. = FALSE
-  )
-}
diff --git a/inst/htmlwidgets/lib/mathjax/cdn.js b/inst/htmlwidgets/lib/mathjax/cdn.js
new file mode 100644
index 0000000000..f59ae042c5
--- /dev/null
+++ b/inst/htmlwidgets/lib/mathjax/cdn.js
@@ -0,0 +1,4 @@
+var script = document.createElement("script");
+script.type = "text/javascript";
+script.src  = "https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.4/MathJax.js?config=TeX-AMS-MML_SVG";
+document.getElementsByTagName("head")[0].appendChild(script);

From 8cc9b917ee9d1a70685e6d474e98b8e7feb28ca2 Mon Sep 17 00:00:00 2001
From: Carson Sievert <cpsievert1@gmail.com>
Date: Wed, 6 Jun 2018 17:26:39 -0500
Subject: [PATCH 3/7] fix bug; document

---
 R/layout.R    | 18 +++++++++++++-----
 man/config.Rd | 20 +++++++++++++++-----
 2 files changed, 28 insertions(+), 10 deletions(-)

diff --git a/R/layout.R b/R/layout.R
index b6a3c74d05..cd9f302e3a 100644
--- a/R/layout.R
+++ b/R/layout.R
@@ -91,6 +91,12 @@ rangeslider <- function(p, start = NULL, end = NULL, ...) {
 #' @param collaborate include the collaborate mode bar button (unique to the R pkg)?
 #' @param cloud include the send data to cloud button?
 #' @param locale locale to use. See [here](https://github.com/plotly/plotly.js/tree/master/dist#to-include-localization) for more info.
+#' @param mathjax whether or not to add [MathJax rendering support](https://github.com/plotly/plotly.js/tree/master/dist#to-support-mathjax).
+#' Note that plotly uses SVG-based mathjax rendering which won't play nicely with 
+#' HTML-based rendering (e.g., rmarkdown documents). In this case, you may want to 
+#' consider `<iframe>`-ing your plotly graph(s) into the larger document.
+#' Currently mathjax is loaded externally (meaning an internet
+#' connection is needed to view the graph). Future versions may not have this requirement.
 #' @author Carson Sievert
 #' @export
 #' @examples
@@ -103,16 +109,18 @@ rangeslider <- function(p, start = NULL, end = NULL, ...) {
 #' # remove the plotly logo and collaborate button from modebar
 #' config(p, displaylogo = FALSE, collaborate = FALSE)
 #' 
+#' # enable mathjax
+#' # see more examples at https://plot.ly/r/LaTeX/
+#' plot_ly(x = c(1, 2, 3, 4), y = c(1, 4, 9, 16)) %>%
+#'   layout(title = "$\\text{Some mathjax: }\\alpha+\\beta x$") %>%
+#'   config(mathjax = TRUE)
+#' 
 #' # japanese
 #' config(p, locale = "ja")
 #' # german
 #' config(p, locale = "de")
-#' # swiss-german
-#' config(p, locale = "de-CH")
 #' # spanish
 #' config(p, locale = "es")
-#' # french
-#' config(p, locale = "fr")
 #' # chinese
 #' config(p, locale = "zh-CN")
 #' 
@@ -129,7 +137,7 @@ config <- function(p, ..., collaborate = TRUE, cloud = FALSE, locale = NULL, mat
   
   if (!identical(mathjax, FALSE)) {
     p$dependencies <- c(
-      list(mathjax_dependency()),
+      list(mathjax_cdn()),
       p$dependencies
     )
   }
diff --git a/man/config.Rd b/man/config.Rd
index 0b6c7efbe6..d67466d106 100644
--- a/man/config.Rd
+++ b/man/config.Rd
@@ -4,7 +4,8 @@
 \alias{config}
 \title{Set the default configuration for plotly}
 \usage{
-config(p, ..., collaborate = TRUE, cloud = FALSE, locale = NULL)
+config(p, ..., collaborate = TRUE, cloud = FALSE, locale = NULL,
+  mathjax = FALSE)
 }
 \arguments{
 \item{p}{a plotly object}
@@ -17,6 +18,13 @@ config(p, ..., collaborate = TRUE, cloud = FALSE, locale = NULL)
 \item{cloud}{include the send data to cloud button?}
 
 \item{locale}{locale to use. See \href{https://github.com/plotly/plotly.js/tree/master/dist#to-include-localization}{here} for more info.}
+
+\item{mathjax}{whether or not to add \href{https://github.com/plotly/plotly.js/tree/master/dist#to-support-mathjax}{MathJax rendering support}.
+Note that plotly uses SVG-based mathjax rendering which won't play nicely with
+HTML-based rendering (e.g., rmarkdown documents). In this case, you may want to
+consider \code{<iframe>}-ing your plotly graph(s) into the larger document.
+Currently mathjax is loaded externally (meaning an internet
+connection is needed to view the graph). Future versions may not have this requirement.}
 }
 \description{
 Set the default configuration for plotly
@@ -31,16 +39,18 @@ p <- plot_ly(x = x, y = rnorm(length(x))) \%>\%
 # remove the plotly logo and collaborate button from modebar
 config(p, displaylogo = FALSE, collaborate = FALSE)
 
+# enable mathjax
+# see more examples at https://plot.ly/r/LaTeX/
+plot_ly(x = c(1, 2, 3, 4), y = c(1, 4, 9, 16)) \%>\%
+  layout(title = "$\\\\text{Some mathjax: }\\\\alpha+\\\\beta x$") \%>\%
+  config(mathjax = TRUE)
+
 # japanese
 config(p, locale = "ja")
 # german
 config(p, locale = "de")
-# swiss-german
-config(p, locale = "de-CH")
 # spanish
 config(p, locale = "es")
-# french
-config(p, locale = "fr")
 # chinese
 config(p, locale = "zh-CN")
 

From 194d435907bff802d7b8c8d3f12e1d25663d5b57 Mon Sep 17 00:00:00 2001
From: Carson Sievert <cpsievert1@gmail.com>
Date: Wed, 6 Jun 2018 20:10:53 -0500
Subject: [PATCH 4/7] add support for local MathJax; introduce TeX(); closes
 #375

---
 NAMESPACE                           |  1 +
 R/layout.R                          | 31 ++++++++++-----
 R/mathjax.R                         | 62 +++++++++++++++++++++++------
 R/plotly_build.R                    | 21 ++++++++++
 inst/examples/rmd/MathJax/index.Rmd | 33 +++++++++++++++
 man/TeX.Rd                          | 26 ++++++++++++
 man/config.Rd                       | 15 +++----
 7 files changed, 159 insertions(+), 30 deletions(-)
 create mode 100644 inst/examples/rmd/MathJax/index.Rmd
 create mode 100644 man/TeX.Rd

diff --git a/NAMESPACE b/NAMESPACE
index c6b0f07969..df9367255d 100644
--- a/NAMESPACE
+++ b/NAMESPACE
@@ -81,6 +81,7 @@ S3method(to_basic,default)
 S3method(transmute_,plotly)
 S3method(ungroup,plotly)
 export("%>%")
+export(TeX)
 export(add_annotations)
 export(add_area)
 export(add_bars)
diff --git a/R/layout.R b/R/layout.R
index cd9f302e3a..c7490bf24c 100644
--- a/R/layout.R
+++ b/R/layout.R
@@ -91,12 +91,13 @@ rangeslider <- function(p, start = NULL, end = NULL, ...) {
 #' @param collaborate include the collaborate mode bar button (unique to the R pkg)?
 #' @param cloud include the send data to cloud button?
 #' @param locale locale to use. See [here](https://github.com/plotly/plotly.js/tree/master/dist#to-include-localization) for more info.
-#' @param mathjax whether or not to add [MathJax rendering support](https://github.com/plotly/plotly.js/tree/master/dist#to-support-mathjax).
-#' Note that plotly uses SVG-based mathjax rendering which won't play nicely with 
-#' HTML-based rendering (e.g., rmarkdown documents). In this case, you may want to 
-#' consider `<iframe>`-ing your plotly graph(s) into the larger document.
-#' Currently mathjax is loaded externally (meaning an internet
-#' connection is needed to view the graph). Future versions may not have this requirement.
+#' @param mathjax add [MathJax rendering support](https://github.com/plotly/plotly.js/tree/master/dist#to-support-mathjax).
+#' If `cdn`, mathjax is loaded externally (meaning an internet connection is needed to 
+#' view the graph). If `local`, mathjax must be available locally. IMPORTANT: plotly uses 
+#' SVG-based mathjax rendering which doesn't play nicely with HTML-based rendering 
+#' (e.g., rmarkdown documents). In this case, you may want to consider `<iframe>`-ing 
+#' your plotly graph(s) into the larger document. 
+#' See [here](https://github.com/ropensci/plotly/blob/master/inst/examples/rmd/MathJax/index.Rmd) for an example.
 #' @author Carson Sievert
 #' @export
 #' @examples
@@ -125,7 +126,7 @@ rangeslider <- function(p, start = NULL, end = NULL, ...) {
 #' config(p, locale = "zh-CN")
 #' 
 
-config <- function(p, ..., collaborate = TRUE, cloud = FALSE, locale = NULL, mathjax = FALSE) {
+config <- function(p, ..., collaborate = TRUE, cloud = FALSE, locale = NULL, mathjax = NULL) {
   
   if (!is.null(locale)) {
     p$dependencies <- c(
@@ -135,11 +136,19 @@ config <- function(p, ..., collaborate = TRUE, cloud = FALSE, locale = NULL, mat
     p$x$config$locale <- locale
   }
   
-  if (!identical(mathjax, FALSE)) {
-    p$dependencies <- c(
-      list(mathjax_cdn()),
-      p$dependencies
+  if (!is.null(mathjax)) {
+    mj <- switch(
+      match.arg(mathjax, c("cdn", "local")),
+      cdn = mathjax_cdn(),
+      local = mathjax_local()
     )
+    # if mathjax is already supplied overwrite it; otherwise, prepend it
+    depNames <- sapply(p$dependencies, "[[", "name")
+    if (any(idx <- depNames %in% "mathjax")) {
+      p$dependencies[[which(idx)]] <- mathjax
+    } else {
+      p$dependencies <- c(list(mj), p$dependencies)
+    }
   }
   
   p$x$config <- modify_list(p$x$config, list(...))
diff --git a/R/mathjax.R b/R/mathjax.R
index 05af3885d5..94962fe385 100644
--- a/R/mathjax.R
+++ b/R/mathjax.R
@@ -1,3 +1,30 @@
+#' Render TeX in a plotly graph using MathJax
+#' 
+#' This function makes it slightly easier to render TeX in a plotly graph --
+#' it ensures that MathJax is included with the final result and also
+#' ensures the provided string is surrounded with `$` (this is what plotly.js
+#' uses to declare a string as TeX).
+#' 
+#' @param x a character vector
+#' @export
+#' @seealso [config]
+#' @examples 
+#' 
+#' plot_ly(x = c(1, 2, 3, 4), y = c(1, 4, 9, 16)) %>%
+#'   layout(title = TeX("\\text{Some mathjax: }\\alpha+\\beta x")) %>%
+#'   config(mathjax = "cdn")
+
+TeX <- function(x) {
+  startsWithDollar <- grepl("^\\$", x)
+  endsWithDollar <- grepl("\\$$", x)
+  x <- paste0(if (!startsWithDollar) "$", x, if (!endsWithDollar) "$")
+  prefix_class(x, "TeX")
+}
+
+is.TeX <- function(x) {
+  inherits(x, "TeX")
+}
+
 mathjax_cdn <- function() {
   htmltools::htmlDependency(
     name = "mathjax",
@@ -7,34 +34,45 @@ mathjax_cdn <- function() {
   )
 }
 
-# TODO: wait until there is a more official way to include query parameters
+# TODO: wait until there is a more official way to include query parameters?
 # https://github.com/rstudio/htmltools/issues/98
 mathjax_local <- function() {
+  path <- mathjax_path()
+  
+  mj <- file.path(path, "MathJax.js")
+  if (!file.exists(mj)) stop("Couldn't locate MathJax.js")
+  
+  # parse the version
+  mathjax <- readLines(mj)
+  pat <- 'MathJax.fileversion="[0-9].[0-9].[0-9]'
+  ver <- regmatches(mathjax, regexpr(pat, mathjax))
+  ver <- sub('"', '', strsplit(ver, "=")[[1]][2])
+  
+  # make sure we have access to the right config
+  config <- file.path(path, "config", "TeX-AMS-MML_SVG.js")
+  if (!file.exists(config)) stop("Couldn't locate necessary MathJax config: TeX-AMS-MML_SVG")
+  
   htmltools::htmlDependency(
-    name = "mathjax",
-    version = "2.7.4",
-    src = c(file = mathjax_path()),
-    script = "MathJax.js?config=TeX-AMS-MML_SVG"
+    name = "mathjax", 
+    version = ver, 
+    src = path,
+    script = c("MathJax.js", "config/TeX-AMS-MML_SVG.js")
   )
 }
 
 
 mathjax_path <- function() {
   path <- Sys.getenv("PLOTLY_MATHJAX_PATH", NA)
+  
   if (!is.na(path)) {
     mj <- file.path(path, "MathJax.js")
     if (!file.exists(mj)) stop("Couldn't find 'MathJax.js' file in local directory")
     return(path)
   }
   
-  if (system.file(package = "rmarkdown") != "") {
-    # Note, this should throw an informative error if the path isn't found
-    return(getFromNamespace("pandoc_mathjax_local_path", "rmarkdown")())
-  } 
-  
   stop(
-    "To use a local version of MathJax with plotly, either set the PLOTLY_MATHJAX_PATH",
-    "environment variable to the location of MathJax or install rmarkdown.",
+    "To use a local version of MathJax with plotly, set the PLOTLY_MATHJAX_PATH",
+    "environment variable to the location of MathJax.",
     call. = FALSE
   )
 }
diff --git a/R/plotly_build.R b/R/plotly_build.R
index 212afc1d2f..81e9e2e8af 100644
--- a/R/plotly_build.R
+++ b/R/plotly_build.R
@@ -371,6 +371,27 @@ plotly_build.plotly <- function(p, registerFrames = TRUE) {
   # box up 'data_array' attributes where appropriate
   p <- verify_attr_spec(p)
   
+  
+  verify_mathjax <- function(p) {
+    hasMathjax <- "mathjax" %in% sapply(p$dependencies, "[[", "name")
+    if (hasMathjax) return(p)
+    
+    hasTeX <- any(rapply(p$x, is.TeX))
+    if (!hasTeX) return(p)
+    
+    # TODO: it would be much better to add the dependency here, but
+    # htmlwidgets doesn't currently support adding dependencies at print-time!
+    warning(
+      "Detected the use of `TeX()`, but mathjax has not been specified. ",
+      "Try running `config(.Last.value, mathjax = 'cdn')`",
+      call. = FALSE
+    )
+    p
+  }
+  
+  # make sure we're including mathjax (if TeX() is used)
+  p <- verify_mathjax(p)
+  
   # if a partial bundle was specified, make sure it supports the visualization
   p <- verify_partial_bundle(p)
   
diff --git a/inst/examples/rmd/MathJax/index.Rmd b/inst/examples/rmd/MathJax/index.Rmd
new file mode 100644
index 0000000000..1d7bbccd7e
--- /dev/null
+++ b/inst/examples/rmd/MathJax/index.Rmd
@@ -0,0 +1,33 @@
+---
+title: "Render plotly MathJax inside rmarkdown"
+output: html_document
+---
+
+Some HTML-based MathJax:
+
+$$ \alpha+\beta $$
+
+You _could_ print this this **plotly** graph with SVG-based rendering, but it would break the HTML-based rendering of **rmarkdown**!
+
+```{r message = FALSE}
+library(plotly)
+
+p <- plotly_empty() %>%
+  add_trace(x = 1, y = 1, text = "$\\alpha$", mode = "text", size = I(1000)) %>%
+  config(mathjax = "cdn")
+```
+
+Instead, use something like the **widgetframe** package to create a responsive iframe. This ensures the SVG-based rendering that plotly requires is done in isolation (i.e., independent of **rmarkdown**'s HTML-based rendering).
+
+```{r}
+widgetframe::frameableWidget(p)
+```
+
+Or, do it the old-fashioned way by saving your plotly graph to an HTML file and use an HTML `<iframe>` to 
+
+```{r}
+htmlwidgets::saveWidget(p, "my-plotly-plot.html")
+```
+
+
+<iframe src="my-plotly-plot.html" width="100%" height="400" id="igraph" scrolling="no" seamless="seamless" frameBorder="0"> </iframe>
diff --git a/man/TeX.Rd b/man/TeX.Rd
new file mode 100644
index 0000000000..38b454b6d6
--- /dev/null
+++ b/man/TeX.Rd
@@ -0,0 +1,26 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/mathjax.R
+\name{TeX}
+\alias{TeX}
+\title{Render TeX in a plotly graph using MathJax}
+\usage{
+TeX(x)
+}
+\arguments{
+\item{x}{a character vector}
+}
+\description{
+This function makes it slightly easier to render TeX in a plotly graph --
+it ensures that MathJax is included with the final result and also
+ensures the provided string is surrounded with \code{$} (this is what plotly.js
+uses to declare a string as TeX).
+}
+\examples{
+
+plot_ly(x = c(1, 2, 3, 4), y = c(1, 4, 9, 16)) \%>\%
+  layout(title = TeX("\\\\text{Some mathjax: }\\\\alpha+\\\\beta x")) \%>\%
+  config(mathjax = "cdn")
+}
+\seealso{
+\link{config}
+}
diff --git a/man/config.Rd b/man/config.Rd
index d67466d106..8019c762eb 100644
--- a/man/config.Rd
+++ b/man/config.Rd
@@ -5,7 +5,7 @@
 \title{Set the default configuration for plotly}
 \usage{
 config(p, ..., collaborate = TRUE, cloud = FALSE, locale = NULL,
-  mathjax = FALSE)
+  mathjax = NULL)
 }
 \arguments{
 \item{p}{a plotly object}
@@ -19,12 +19,13 @@ config(p, ..., collaborate = TRUE, cloud = FALSE, locale = NULL,
 
 \item{locale}{locale to use. See \href{https://github.com/plotly/plotly.js/tree/master/dist#to-include-localization}{here} for more info.}
 
-\item{mathjax}{whether or not to add \href{https://github.com/plotly/plotly.js/tree/master/dist#to-support-mathjax}{MathJax rendering support}.
-Note that plotly uses SVG-based mathjax rendering which won't play nicely with
-HTML-based rendering (e.g., rmarkdown documents). In this case, you may want to
-consider \code{<iframe>}-ing your plotly graph(s) into the larger document.
-Currently mathjax is loaded externally (meaning an internet
-connection is needed to view the graph). Future versions may not have this requirement.}
+\item{mathjax}{add \href{https://github.com/plotly/plotly.js/tree/master/dist#to-support-mathjax}{MathJax rendering support}.
+If \code{cdn}, mathjax is loaded externally (meaning an internet connection is needed to
+view the graph). If \code{local}, mathjax must be available locally. IMPORTANT: plotly uses
+SVG-based mathjax rendering which doesn't play nicely with HTML-based rendering
+(e.g., rmarkdown documents). In this case, you may want to consider \code{<iframe>}-ing
+your plotly graph(s) into the larger document.
+See \href{https://github.com/ropensci/plotly/blob/master/inst/examples/rmd/MathJax/index.Rmd}{here} for an example.}
 }
 \description{
 Set the default configuration for plotly

From 740ee6c2c9ed0f6a08a06b13056d9ca9c1031d2c Mon Sep 17 00:00:00 2001
From: Carson Sievert <cpsievert1@gmail.com>
Date: Thu, 7 Jun 2018 10:15:13 -0500
Subject: [PATCH 5/7] fix MathJax path in orca(), improve docs

---
 R/layout.R                          | 12 ++++++------
 R/orca.R                            | 11 +++++------
 inst/examples/rmd/MathJax/index.Rmd |  6 +++---
 man/config.Rd                       | 12 ++++++------
 man/orca.Rd                         |  9 ++++-----
 5 files changed, 24 insertions(+), 26 deletions(-)

diff --git a/R/layout.R b/R/layout.R
index c7490bf24c..0ffe4757dc 100644
--- a/R/layout.R
+++ b/R/layout.R
@@ -92,12 +92,12 @@ rangeslider <- function(p, start = NULL, end = NULL, ...) {
 #' @param cloud include the send data to cloud button?
 #' @param locale locale to use. See [here](https://github.com/plotly/plotly.js/tree/master/dist#to-include-localization) for more info.
 #' @param mathjax add [MathJax rendering support](https://github.com/plotly/plotly.js/tree/master/dist#to-support-mathjax).
-#' If `cdn`, mathjax is loaded externally (meaning an internet connection is needed to 
-#' view the graph). If `local`, mathjax must be available locally. IMPORTANT: plotly uses 
-#' SVG-based mathjax rendering which doesn't play nicely with HTML-based rendering 
-#' (e.g., rmarkdown documents). In this case, you may want to consider `<iframe>`-ing 
-#' your plotly graph(s) into the larger document. 
-#' See [here](https://github.com/ropensci/plotly/blob/master/inst/examples/rmd/MathJax/index.Rmd) for an example.
+#' If `"cdn"`, mathjax is loaded externally (meaning an internet connection is needed for 
+#' TeX rendering). If `"local"`, the PLOTLY_MATHJAX_PATH environment variable must be
+#' set to the location (a local file path) of MathJax. IMPORTANT: plotly uses SVG-based 
+#' mathjax rendering which doesn't play nicely with HTML-based rendering (e.g., rmarkdown documents). 
+#' In this case, consider `<iframe>`-ing your plotly graph(s) into the larger document 
+#' (see [here](https://github.com/ropensci/plotly/blob/master/inst/examples/rmd/MathJax/index.Rmd) for an example).
 #' @author Carson Sievert
 #' @export
 #' @examples
diff --git a/R/orca.R b/R/orca.R
index 415e1ce97c..a863f1896b 100644
--- a/R/orca.R
+++ b/R/orca.R
@@ -11,9 +11,10 @@
 #' Applies to all output images.
 #' @param height Sets the image height. If not set, defaults to `layout.height` value. 
 #' Applies to all output images.
-#' @param mathjax whether or not to specify a path to mathjax (required to export LaTeX characters).
-#' This should 'just work' in RStudio, but outside RStudio, you may have to set 
-#' the PLOTLY_MATHJAX_PATH environment variable to the location of MathJax.
+#' @param mathjax whether or not to include MathJax (required to render [TeX]).
+#' If `TRUE`, the PLOTLY_MATHJAX_PATH environment variable must be set and point 
+#' to the location of MathJax (this variable is also used to render [TeX] in 
+#' interactive graphs, see [config]).
 #' @param parallel_limit Sets the limit of parallel tasks run.
 #' @param verbose Turn on verbose logging on stdout.
 #' @param debug Starts app in debug mode and turn on verbose logs on stdout.
@@ -25,9 +26,7 @@
 #' 
 #' \dontrun{
 #' p <- plot_ly(z = ~volcano) %>% add_surface()
-#' orca(p, "surface-plot.png")
 #' orca(p, "surface-plot.svg")
-#' orca(p, "surface-plot.pdf")
 #' }
 #' 
 
@@ -65,7 +64,7 @@ orca <- function(p, file = "plot.png", format = tools::file_ext(file),
   if (!is.null(height)) args <- c(args, "--height", height)
   if (!is.null(parallel_limit)) args <- c(args, "--parallel-limit", parallel_limit)
   if (!is.na(mapbox_token())) args <- c(args, "--mapbox-access-token", mapbox_token())
-  if (isTRUE(mathjax)) args <- c(args, "--mathjax", mathjax_path())
+  if (isTRUE(mathjax)) args <- c(args, "--mathjax", file.path(mathjax_path(), "MathJax.js"))
      
   # TODO: point to local topojson? Should this only work if plot_geo(standalone = TRUE)?
   try_library("processx", "orca")
diff --git a/inst/examples/rmd/MathJax/index.Rmd b/inst/examples/rmd/MathJax/index.Rmd
index 1d7bbccd7e..1303102811 100644
--- a/inst/examples/rmd/MathJax/index.Rmd
+++ b/inst/examples/rmd/MathJax/index.Rmd
@@ -7,7 +7,7 @@ Some HTML-based MathJax:
 
 $$ \alpha+\beta $$
 
-You _could_ print this this **plotly** graph with SVG-based rendering, but it would break the HTML-based rendering of **rmarkdown**!
+You _could_ print this **plotly** graph with SVG-based rendering, but it would break the HTML-based rendering of **rmarkdown**!
 
 ```{r message = FALSE}
 library(plotly)
@@ -17,13 +17,13 @@ p <- plotly_empty() %>%
   config(mathjax = "cdn")
 ```
 
-Instead, use something like the **widgetframe** package to create a responsive iframe. This ensures the SVG-based rendering that plotly requires is done in isolation (i.e., independent of **rmarkdown**'s HTML-based rendering).
+Instead, use something like the **widgetframe** package to create a responsive iframe which ensure the SVG-based rendering that plotly requires is done independently of **rmarkdown**'s HTML-based rendering.
 
 ```{r}
 widgetframe::frameableWidget(p)
 ```
 
-Or, do it the old-fashioned way by saving your plotly graph to an HTML file and use an HTML `<iframe>` to 
+Or, do it the old-fashioned way: save your plotly graph to an HTML file via `htmlwidgets::saveWidget()` then use an HTML `<iframe>`
 
 ```{r}
 htmlwidgets::saveWidget(p, "my-plotly-plot.html")
diff --git a/man/config.Rd b/man/config.Rd
index 8019c762eb..2bfb60cac4 100644
--- a/man/config.Rd
+++ b/man/config.Rd
@@ -20,12 +20,12 @@ config(p, ..., collaborate = TRUE, cloud = FALSE, locale = NULL,
 \item{locale}{locale to use. See \href{https://github.com/plotly/plotly.js/tree/master/dist#to-include-localization}{here} for more info.}
 
 \item{mathjax}{add \href{https://github.com/plotly/plotly.js/tree/master/dist#to-support-mathjax}{MathJax rendering support}.
-If \code{cdn}, mathjax is loaded externally (meaning an internet connection is needed to
-view the graph). If \code{local}, mathjax must be available locally. IMPORTANT: plotly uses
-SVG-based mathjax rendering which doesn't play nicely with HTML-based rendering
-(e.g., rmarkdown documents). In this case, you may want to consider \code{<iframe>}-ing
-your plotly graph(s) into the larger document.
-See \href{https://github.com/ropensci/plotly/blob/master/inst/examples/rmd/MathJax/index.Rmd}{here} for an example.}
+If \code{"cdn"}, mathjax is loaded externally (meaning an internet connection is needed for
+TeX rendering). If \code{"local"}, the PLOTLY_MATHJAX_PATH environment variable must be
+set to the location (a local file path) of MathJax. IMPORTANT: plotly uses SVG-based
+mathjax rendering which doesn't play nicely with HTML-based rendering (e.g., rmarkdown documents).
+In this case, consider \code{<iframe>}-ing your plotly graph(s) into the larger document
+(see \href{https://github.com/ropensci/plotly/blob/master/inst/examples/rmd/MathJax/index.Rmd}{here} for an example).}
 }
 \description{
 Set the default configuration for plotly
diff --git a/man/orca.Rd b/man/orca.Rd
index cd7db4948e..4ab229a3ea 100644
--- a/man/orca.Rd
+++ b/man/orca.Rd
@@ -23,9 +23,10 @@ Applies to all output images.}
 \item{height}{Sets the image height. If not set, defaults to \code{layout.height} value.
 Applies to all output images.}
 
-\item{mathjax}{whether or not to specify a path to mathjax (required to export LaTeX characters).
-This should 'just work' in RStudio, but outside RStudio, you may have to set
-the PLOTLY_MATHJAX_PATH environment variable to the location of MathJax.}
+\item{mathjax}{whether or not to include MathJax (required to render \link{TeX}).
+If \code{TRUE}, the PLOTLY_MATHJAX_PATH environment variable must be set and point
+to the location of MathJax (this variable is also used to render \link{TeX} in
+interactive graphs, see \link{config}).}
 
 \item{parallel_limit}{Sets the limit of parallel tasks run.}
 
@@ -44,9 +45,7 @@ see the installation instructions \href{https://github.com/plotly/orca#installat
 
 \dontrun{
 p <- plot_ly(z = ~volcano) \%>\% add_surface()
-orca(p, "surface-plot.png")
 orca(p, "surface-plot.svg")
-orca(p, "surface-plot.pdf")
 }
 
 }

From 9d3c41483a5e25b236ec1417e2e163eef97140f0 Mon Sep 17 00:00:00 2001
From: Carson Sievert <cpsievert1@gmail.com>
Date: Thu, 7 Jun 2018 10:16:28 -0500
Subject: [PATCH 6/7] fix example

---
 R/layout.R    | 4 ++--
 man/config.Rd | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/R/layout.R b/R/layout.R
index 0ffe4757dc..6901e48f4a 100644
--- a/R/layout.R
+++ b/R/layout.R
@@ -113,8 +113,8 @@ rangeslider <- function(p, start = NULL, end = NULL, ...) {
 #' # enable mathjax
 #' # see more examples at https://plot.ly/r/LaTeX/
 #' plot_ly(x = c(1, 2, 3, 4), y = c(1, 4, 9, 16)) %>%
-#'   layout(title = "$\\text{Some mathjax: }\\alpha+\\beta x$") %>%
-#'   config(mathjax = TRUE)
+#'   layout(title = TeX("\\text{Some mathjax: }\\alpha+\\beta x")) %>%
+#'   config(mathjax = "cdn")
 #' 
 #' # japanese
 #' config(p, locale = "ja")
diff --git a/man/config.Rd b/man/config.Rd
index 2bfb60cac4..022ca96d2e 100644
--- a/man/config.Rd
+++ b/man/config.Rd
@@ -43,8 +43,8 @@ config(p, displaylogo = FALSE, collaborate = FALSE)
 # enable mathjax
 # see more examples at https://plot.ly/r/LaTeX/
 plot_ly(x = c(1, 2, 3, 4), y = c(1, 4, 9, 16)) \%>\%
-  layout(title = "$\\\\text{Some mathjax: }\\\\alpha+\\\\beta x$") \%>\%
-  config(mathjax = TRUE)
+  layout(title = TeX("\\\\text{Some mathjax: }\\\\alpha+\\\\beta x")) \%>\%
+  config(mathjax = "cdn")
 
 # japanese
 config(p, locale = "ja")

From 06eabb439ac7d843a468b99a7ed4230d5e976a91 Mon Sep 17 00:00:00 2001
From: Carson Sievert <cpsievert1@gmail.com>
Date: Thu, 7 Jun 2018 10:18:01 -0500
Subject: [PATCH 7/7] promote use of TeX()

---
 inst/examples/rmd/MathJax/index.Rmd | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/inst/examples/rmd/MathJax/index.Rmd b/inst/examples/rmd/MathJax/index.Rmd
index 1303102811..21b390b0c7 100644
--- a/inst/examples/rmd/MathJax/index.Rmd
+++ b/inst/examples/rmd/MathJax/index.Rmd
@@ -13,7 +13,7 @@ You _could_ print this **plotly** graph with SVG-based rendering, but it would b
 library(plotly)
 
 p <- plotly_empty() %>%
-  add_trace(x = 1, y = 1, text = "$\\alpha$", mode = "text", size = I(1000)) %>%
+  add_trace(x = 1, y = 1, text = TeX("\\alpha"), mode = "text", size = I(1000)) %>%
   config(mathjax = "cdn")
 ```