`fig-scap` is hard to find in our docs

[cscheid]

Looking for "short caption" in quarto docs yields the code cell options, but nothing on LaTeX authoring.

See #4776 for the confusion this generates.

[cderv]

Possibly the same for other figure attributes that we handle in Lua

quarto-cli/src/resources/filters/common/figures.lua

Lines 4 to 12 in be1f37e

	-- constants for figure attributes
	kFigAlign = "fig-align"
	kFigEnv = "fig-env"
	kFigAlt = "fig-alt"
	kFigPos = "fig-pos"
	kFigCap = "fig-cap"
	kFigScap = "fig-scap"
	kResizeWidth = "resize.width"
	kResizeHeight = "resize.height"

They are based possibly on knitr options, ported to Jupyter support and direct Markdown syntax support.

[cwickham]

Of those mentioned by @cderv, these are already described in the docs:

• fig-align
• fig-env
• fig-alt
• fig-pos

I propose fig-scap should be described in LaTeX Figures where fig-env and fig-pos are currently.

Questions:

• Is fig-cap an alternative to providing the caption like ![Caption]()? Should we describe it in Figure Basics?
• When would someone use resize.width or resize.height? (And why do they use . not -?)
• Are there attributes that can be added in other contexts (like tables, headings etc.) that may suffer from this same lack of documentation? Because these don't exist in the "Reference" I know I only discover them by happening upon them in the "Guide".

[cscheid]

• Is fig-cap an alternative to providing the caption like ![Caption]()? Should we describe it in Figure Basics?

fig-cap is shown in https://quarto.org/docs/authoring/figures.html#cross-references, but it probably deserves a more prominent explanation. We use fig-cap in knitr and jupyter code cells that produce figures.

[cwickham]

But would you ever use fig-cap as an attribute outside of computation? E.g. like ![](some-image.png){fig-cap="Some caption"}.

[cwickham]

fig-cap as a chunk option is also covered in https://quarto.org/docs/authoring/figures.html#computations, and https://quarto.org/docs/computations/r.html#chunk-options and on all the Code and Document Reference pages. So, I suggest if no one would ever use it outside of computation it probably needs no further coverage.

[cderv]

When would someone use resize.width or resize.height? (And why do they use . not -?)

I think this is only for knitr backward compatibility. They are knitr options for plots: https://yihui.org/knitr/options/#plots
and only use in Quarto in the R part of the code - this is for tikz support in knitr If I am right: ec2b971

So I would say, no need to document further in fact (and they probably use . because that is what you would expect in knitr (this is a sign to me that by design they should not be used with Quarto directly)