fix #2023: reStructuredText figure caption is no longer escaped, and …

…alt text can be independently specified via the fig.alt option (#2269)

Co-authored-by: Yihui Xie <xie@yihui.name>

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: knitr
 Type: Package
 Title: A General-Purpose Package for Dynamic Report Generation in R
-Version: 1.43.3
+Version: 1.43.4
 Authors@R: c(
     person("Yihui", "Xie", role = c("aut", "cre"), email = "xie@yihui.name", comment = c(ORCID = "0000-0003-0645-5666")),
     person("Abhraneel", "Sarma", role = "ctb"),

NEWS.md

@@ -10,6 +10,8 @@
 
 - When the chunk option `dev = 'svglite'`, the `svglite` device should be used to record plots (thanks, @Darxor, #2272).
 
+- Figure captions are no longer escaped for reStructuredText output, and the alt text can also be specified via the `fig.alt` chunk option now (thanks, @trevorld, #2023).
+
 # CHANGES IN knitr VERSION 1.43
 
 ## NEW FEATURES

R/hooks-html.R

@@ -55,12 +55,15 @@ hook_animation = function(options) {
   paste0(res, if (tag == 'object') '></object>' else ' />')
 }
 
-.img.cap = function(options, alt = FALSE) {
+.img.cap = function(options, alt = FALSE, escape = FALSE) {
   cap = options$fig.cap %n% {
     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 (alt) {
+    alt = options$fig.alt %n% cap
+    return(if (escape) escape_html(alt) else alt)
+  }
   if (is_blank(cap)) return(cap)
   paste0(create_label(
     options$fig.lp, options$label,
@@ -140,7 +143,7 @@ hook_ffmpeg = function(x, options, format = 'webm') {
     sprintf('width="%s"', options$out.width),
     sprintf('height="%s"', options$out.height), opts
   )
-  cap = .img.cap(options, alt = TRUE)
+  cap = .img.cap(options, alt = TRUE, escape = TRUE)
   if (cap != '') cap = sprintf('<p>%s</p>', cap)
   sprintf(
     '<video %s><source src="%s" />%s</video>', trimws(opts),

R/hooks-rst.R

@@ -5,15 +5,16 @@
 hook_plot_rst = function(x, options) {
   if (options$fig.show == 'animate') return(hook_plot_html(x, options))
 
-  cap = .img.cap(options, alt = TRUE)
+  cap = .img.cap(options)
+  alt = .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
   make_directive(
     'figure',
     paste0(opts_knit$get('base.url'), .upload.url(x)),
     c(align = if (options$fig.align == 'default') NULL else options$fig.align,
-      alt = cap, width = options$out.width, height = options$out.height),
+      alt = alt, width = options$out.width, height = options$out.height),
     cap
   )
 }

R/output.R

@@ -653,7 +653,7 @@ add_html_caption = function(options, code, id = NULL) {
   if (cap == '' && !length(id)) return(code)
 
   if (length(id)) {
-    alt = .img.cap(options, alt = TRUE)
+    alt = .img.cap(options, alt = TRUE, escape = TRUE)
     if (cap == alt && cap != '') {
       # both are the same, so insert cap with id
       alttext = sprintf('<p class="caption" id="%s">%s</p>\n', id, cap)

tests/testit/test-utils.R

@@ -137,11 +137,11 @@ opts = list(
 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 "caption" <>.')
+  (.img.cap(opts, TRUE, TRUE)  %==% 'Figure "caption" <>.')
 
   opts$fig.alt = 'Figure "alternative text" <>.'
 
-  (.img.cap(opts, TRUE)  %==% 'Figure &quot;alternative text&quot; &lt;&gt;.')
+  (.img.cap(opts, TRUE, TRUE)  %==% 'Figure &quot;alternative text&quot; &lt;&gt;.')
   (.img.cap(opts, FALSE)  %==% opts$fig.cap)
 
   (.img.cap(list(fig.cap = '', fig.alt = "alt"), FALSE) %==% "")