Add a fig.alt chunk option to provide alternative text different than…

… fig.cap (#1900)

close #1879 and close rstudio/rmarkdown#1867

NEWS.md

@@ -2,6 +2,8 @@
 
 ## NEW FEATURES
 
+- Added a new chunk option `fig.alt` for users to specify the alternative text in the `alt` attribute of the `<img>` tag  (images). Previously, the `alt` attribute takes value from the chunk option `fig.cap` (it still does so if `fig.alt` is `NULL`). If there are multiple plots/images in a chunk, you can pass a character vector to `fig.alt`, and it will be applied to individual images (thanks, @cderv, #1900).
+
 - `include_url()` and `include_app()` can now take a vector of URLs (thanks, @cderv, #1948).
 
 - The `sql` engine now correctly captures error with the chunk option `error = TRUE` (thanks, @colearendt, rstudio/rmarkdown#1208).

R/defaults.R

@@ -115,6 +115,7 @@ opts_chunk_attr = local({
   opts$external = opts$sanitize = NULL  # hide these two rare options
   opts$fig.process = 'function'
   opts$fig.asp = 'numeric'
+  opts$fig.alt = 'character'
   opts$fig.dim = 'list'
   opts$R.options = 'list'
   opts$cache.comments = 'logical'
@@ -164,7 +165,7 @@ set_alias = function(...) {
 #' }
 #' @include hooks-html.R
 opts_knit = new_defaults(list(
-  progress = TRUE, verbose = FALSE, eval.after = 'fig.cap',
+  progress = TRUE, verbose = FALSE, eval.after = c('fig.cap', 'fig.alt'),
   base.dir = NULL, base.url = NULL, root.dir = NULL, child.path = '',
   upload.fun = identity, global.device = FALSE, global.par = FALSE,
   concordance = FALSE, documentation = 1L, self.contained = TRUE,

R/hooks-html.R

@@ -56,8 +56,8 @@ hook_animation = function(options) {
     if (is.null(pandoc_to())) sprintf('plot of chunk %s', options$label) else ''
   }
   if (length(cap) == 0) cap = ''
+  if (alt) return(escape_html(options$fig.alt %n% cap))
   if (is_blank(cap)) return(cap)
-  if (alt) return(escape_html(cap))
   paste0(create_label(
     options$fig.lp, options$label,
     if (options$fig.num > 1L && options$fig.show == 'asis') c('-', options$fig.cur)

R/hooks-md.R

@@ -51,7 +51,8 @@ hook_plot_md_base = function(x, options) {
   plot1 = ai || options$fig.cur <= 1L
   plot2 = ai || options$fig.cur == options$fig.num
   to = pandoc_to(); from = pandoc_from()
-  if (is.null(w) && is.null(h) && is.null(s) && a == 'default' && !(pandoc_html && in_bookdown)) {
+  if (is.null(w) && is.null(h) && is.null(s) && is.null(options$fig.alt) &&
+      a == 'default' && !(pandoc_html && in_bookdown)) {
     # append <!-- --> to ![]() to prevent the figure environment in these cases
     nocap = cap == '' && !is.null(to) && !grepl('^markdown', to) &&
       (options$fig.num == 1 || ai) && !grepl('-implicit_figures', from)

R/hooks-rst.R

@@ -5,7 +5,7 @@
 hook_plot_rst = function(x, options) {
   if (options$fig.show == 'animate') return(hook_plot_html(x, options))
 
-  cap = .img.cap(options)
+  cap = .img.cap(options, alt = TRUE)
   # TODO: add all options for figure
   # See http://docutils.sourceforge.net/docs/ref/rst/directives.html#image
   # http://docutils.sourceforge.net/docs/ref/rst/directives.html#figure

R/plot.R

@@ -218,7 +218,7 @@ is_low_change = function(p1, p2) {
 
 # recycle some plot options such as fig.cap, out.width/height, etc when there
 # are multiple plots per chunk
-.recyle.opts = c('fig.cap', 'fig.scap', 'fig.env', 'fig.pos', 'fig.subcap',
+.recyle.opts = c('fig.cap', 'fig.scap', 'fig.alt', 'fig.env', 'fig.pos', 'fig.subcap',
                  'out.width', 'out.height', 'out.extra', 'fig.link')
 
 # when passing options to plot hooks, reduce the recycled options to scalars

tests/testit/test-utils.R

@@ -144,12 +144,22 @@ assert(
 )
 rm(list = 'cw')
 
-opts = list(fig.cap = 'Figure "caption" <>.', fig.lp = 'Fig:', label = 'foo')
-assert(
-  '.img.cap() generates the figure caption and alt attribute',
-  .img.cap(opts, FALSE) %==% opts$fig.cap,
-  .img.cap(opts, TRUE)  %==% 'Figure &quot;caption&quot; &lt;&gt;.'
+opts = list(
+  fig.cap = 'Figure "caption" <>.', fig.lp = 'Fig:', label = 'foo'
 )
+assert('.img.cap() generates the figure caption and alt attribute', {
+  (.img.cap(list(fig.cap = NULL), FALSE) %==% "")
+  (.img.cap(opts, FALSE) %==% opts$fig.cap)
+  (.img.cap(opts, TRUE)  %==% 'Figure &quot;caption&quot; &lt;&gt;.')
+
+  opts$fig.alt = 'Figure "alternative text" <>.'
+
+  (.img.cap(opts, TRUE)  %==% 'Figure &quot;alternative text&quot; &lt;&gt;.')
+  (.img.cap(opts, FALSE)  %==% opts$fig.cap)
+
+  (.img.cap(list(fig.cap = '', fig.alt = "alt"), FALSE) %==% "")
+  (.img.cap(list(fig.cap = '', fig.alt = "alt"), TRUE) %==% "alt")
+})
 
 z = as.strict_list(list(a = 1, aa = 2, bbb = 3))
 assert(