fix MathJax path in orca(), improve docs

Author: cpsievert

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

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")

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")