Allow restricting image formats

NEWS.md

@@ -1,5 +1,9 @@
 # roxygen2 (development version)
 
+* roxygen2 now only only includes PDF figures generated via markdown in
+  the PDF manual, and only includes SVG figures generated via markdown
+  in the HTML manual (#1399).
+
 * The new `knitr_chunk_options` option (in the `Roxygen` entry of
   `DESCRIPTION` or in `man/roxygen/meta.R`) is added to the knitr chunk
   options that roxygen2 uses for markdown code blocks and inline

R/markdown.R

@@ -424,12 +424,44 @@ mdxml_link_text <- function(xml_contents, state) {
   paste0(text, collapse = "")
 }
 
-mdxml_image = function(xml) {
+mdxml_image <- function(xml) {
   dest <- xml_attr(xml, "destination")
   title <- xml_attr(xml, "title")
+  fmt <- get_image_format(dest)
   paste0(
+    if (fmt == "html") "\\if{html}{",
+    if (fmt == "pdf") "\\if{pdf}{",
     "\\figure{", dest, "}",
-    if (nchar(title)) paste0("{", title, "}")
+    if (nchar(title)) paste0("{", title, "}"),
+    if (fmt %in% c("html", "pdf")) "}"
+  )
+}
+
+get_image_format <- function(path) {
+  should_restrict <- roxy_meta_get("restrict_image_formats") %||% TRUE
+  if (!should_restrict) {
+    return("all")
+  }
+
+  path <- tolower(path)
+  rx <- default_image_formats()
+  html <- grepl(rx$html, path)
+  pdf <- grepl(rx$pdf, path)
+  if (html && pdf) {
+    "all"
+  } else if (html) {
+    "html"
+  } else if (pdf) {
+    "pdf"
+  } else {
+    "all"
+  }
+}
+
+default_image_formats <- function() {
+  list(
+    html = "[.](jpg|jpeg|gif|png|svg)$",
+    pdf = "[.](jpg|jpeg|gif|png|pdf)$"
   )
 }
 

R/options.R

@@ -30,6 +30,10 @@
 #'
 #' * `knitr_chunk_options`: default chunk options used for knitr.
 #'
+#' * `restrict_image_formats`: if `TRUE` then PDF images are only included in the
+#'   PDF manual, and SVG images are only included in the HTML manual.
+#'   (This only applies to images supplied via markdown.)
+#'
 #' @section How to set:
 #' Either set in `DESCRIPTION`:
 #'
@@ -63,7 +67,8 @@ load_options <- function(base_path = ".") {
     r6 = TRUE,
     current_package = NA_character_,
     rd_family_title = list(),
-    knitr_chunk_options = NULL
+    knitr_chunk_options = NULL,
+    restrict_image_formats = TRUE
   )
 
   unknown_opts <- setdiff(names(opts), names(defaults))
@@ -145,4 +150,3 @@ local_roxy_meta_set <- function(key, value, envir = caller_env()) {
 
   roxy_meta_set(key, value)
 }
-

tests/testthat/_snaps/markdown.md

@@ -88,3 +88,24 @@
       }
 
 
+# image formats work
+
+    Code
+      roc_proc_text(rd_roclet(),
+      "\n      #' Title\n      #'\n      #' ![](example.svg \"Plot title 1\")\n      #' ![](example.pdf \"Plot title 2\")\n      #' ![](example.PNG \"Plot title 3\")\n      #' @md\n      foo <- function() { }\n    ")[[
+        1]]
+    Output
+      % Generated by roxygen2: do not edit by hand
+      % Please edit documentation in ./<text>
+      \name{foo}
+      \alias{foo}
+      \title{Title}
+      \usage{
+      foo()
+      }
+      \description{
+      \if{html}{\figure{example.svg}{Plot title 1}}
+      \if{pdf}{\figure{example.pdf}{Plot title 2}}
+      \figure{example.PNG}{Plot title 3}
+      }
+

tests/testthat/test-markdown.R

@@ -648,3 +648,17 @@ test_that("can override default options", {
   ")[[1]]
   expect_match(out$get_section("description")$value, "###", fixed = TRUE)
 })
+
+test_that("image formats work", {
+  expect_snapshot(
+    roc_proc_text(rd_roclet(), "
+      #' Title
+      #'
+      #' ![](example.svg \"Plot title 1\")
+      #' ![](example.pdf \"Plot title 2\")
+      #' ![](example.PNG \"Plot title 3\")
+      #' @md
+      foo <- function() { }
+    ")[[1]]
+  )
+})

vignettes/rd-formatting.Rmd

@@ -332,6 +332,9 @@ Be aware that plots can quickly increase the size of your package leading to cha
 #' ```
 ```
 
+By default roxygen2 only includes PDF images in the PDF manual, and SVG images in the HTML manual.
+If you want to avoid this restriction, set the `restrict_image_formats` roxygen2 option to `FALSE`, see `?load_options`.
+
 ## Possible problems
 
 ### Some Rd tags can't contain markdown