Support `-scap` in Float crossrefs consistently across formats and input options

[BradyAJohnston]

Bug description

Minor issues with the fig-scap: when there are multiple subfigures. When using subfigures and subcaptions, the fig-scap is no longer used in the list of figures, instead the full caption is used and the scap is ignored.

---
title: "scratch"
toc: true
format: 
  pdf:
    table-of-contents: true
    lof: true
---

```{r}
#| fig-cap: "Long caption 1."
#| fig-scap: "Short1"
#| echo: false
plot(mtcars)
```

```{r}
#| layout-ncol: 2
#| label: fig-charts
#| echo: false
#| fig-cap: "Overall longer caption."
#| fig-scap: "Short2"
#| fig-subcap: 
#|   - "Long caption 2."
#|   - "Long caption 3."
plot(mtcars)
plot(cars)
```

Related to this as well is the potential for using scap in divs for markdown figures, ![](). Not necessarily a bug as I'm unsure if scap is supported for HTML output.

RStudio Build 576. MacOS 12.6, Intel Macbook Pro 15-inch (2017).

Checklist

• Please include a minimal, fully reproducible example in a single .qmd file? Please provide the whole file rather than the snippet you believe is causing the issue.
• Please format your issue so it is easier for us to read the bug report.
• Please document the RStudio IDE version you're running (if applicable), by providing the value displayed in the "About RStudio" main menu dialog?
• Please document the operating system you're running. If on Linux, please provide the specific distribution.

[cscheid]

Related to this as well is the potential for using scap in divs for markdown figures, ![](). Not necessarily a bug as I'm unsure if scap is supported for HTML output.

We currently have no use for scap in HTML output because there's currently no "list of figures" or "list of tables" in HTML. But we should, see #2138.

(I'm going to edit the title of this to account for our ongoing crossrefs work in 1.4.)

[cderv]

@cscheid I was looking at how knitr handles fig-scap option for Quarto I stumbled upon this one.
I see you renamed it for consistency across formats, but it should already be dealt with to fix issue with fig-scap when there is subcaption.

See this example - we can see what is happening when we configure subcaption to show in list of figures.

---
title: "scratch"
toc: true
format: 
  pdf:
    lof: true
    include-in-header: 
      text: |
        \PassOptionsToPackage{list=true}{subcaption}
keep-md: true
---

```{r}
#| fig-cap: "Long caption 1."
#| fig-scap: "Short1"
#| echo: false
plot(mtcars)
```

```{r}
#| layout-ncol: 2
#| label: fig-charts
#| echo: false
#| fig-cap: "Overall longer caption."
#| fig-scap: "Short2"
#| fig-subcap: 
#|   - "Long caption 2."
#|   - "Long caption 3."
plot(mtcars)
plot(cars)
```

BTW I am using a trick with header includes because we still need to deal with this

• Allow to pass option to subcaption package in latex (e.g list of figures inclusion) #5347

Anyhow, on the example above, you can see that we are putting the fig-scap onto each plots and not moving it to the main figure like the caption so that it can be handle like caption.

So two things here:

• fig-scap should be handle correctly to be assign to fig-cap - this is a knitr thing.
• fig-scap attributes on figure div should be handled correctly when subfigures.

So similar to other discussion we add where knitr needs to emit the right expected markdown when subfigures.

[cscheid]

fig-scap attributes on figure div should be handled correctly when subfigures.

Just to be clear: fig-scap is one thing (short captions for lists of ...), fig-subcap is another (subcaptions in subfloats).

Are you suggesting that if someone only uses fig-scap, then we should forward it to fig-subcap? That makes sense. I just want to make sure I'm not missing something.

[cderv]

Are you suggesting that if someone only uses fig-scap, then we should forward it to fig-subcap? That makes sense. I just want to make sure I'm not missing something.

Yes this is what I am suggesting.

If you have fig-cap and fig-scap set with one figure in the chunk, the fig-scap will be associated to the only figure.
Now adds fig-subcap because you are using multiple figure, and this time fig-scap is no more used as the short caption of the fig-cap, but it duplicated to go on each subfigure.

I don't think this makes sense right now.

But this also implies that we need a new way to provide short caption for subfigure to go fig-subcap.

I would say markdown way this would be something like

---
title: "test"
format: 
  pdf: 
    lof: true
    include-in-header:
      text: |
        \PassOptionsToPackage{list=true}{subcaption}
  html: default
keep-tex: true
---

::: {#fig-main fig-scap="short caption"}

![Long subcaption 1](demo.png){#fig-sub1 fig-scap="short subcaption 1"}

![Long subcaption 2](demo.png){#fig-sub2 fig-scap="short subcaption2"}

Main Caption
:::

which seems to work already. (you need the subcaption trick to see the lof though - #5347 (comment))

But don't if you provide layout option like

---
title: "test"
format: 
  pdf: 
    lof: true
    include-in-header:
      text: |
        \PassOptionsToPackage{list=true}{subcaption}
  html: default
keep-tex: true
---

::: {#fig-main fig-scap="short caption" layout-ncol=2}

![Long subcaption 1](demo.png){#fig-sub1 fig-scap="short subcaption 1"}

![Long subcaption 2](demo.png){#fig-sub2 fig-scap="short subcaption2"}

Main Caption
:::

This is other issue

• Custom layout for figures does not work anymore for LaTeX  #7309 (comment)

I believe we have several issues related to each other that could be solved together.

I would say when all the markdown syntax are working as we expect, we can then be sure to update knitr and jupyter to produce the expected Markdown