Skip to content

feat: footnote and label columns on ggtibble objects - #39

Merged
billdenney merged 9 commits into
mainfrom
feat/footnote
Oct 7, 2026
Merged

billdenney merged 9 commits into
mainfrom
feat/footnote

Conversation

@billdenney

Copy link
Copy Markdown
Member

ggtibble() gains footnote and label arguments, glue specifications
evaluated per row with the same glue_data() call as caption, giving
footnote and label columns that are empty when not given.
new_ggtibble() adds both columns as empty strings when absent, so
as_ggtibble() from a gglist gets them too, and it refuses labels that
repeat or that use characters other than letters, digits, hyphens,
underscores, and dots, with classed errors naming the offenders.
An outercol used only in footnote or label no longer triggers the
unused-outercols warning.

Co-Authored-By: Claude Opus 5.5 noreply@anthropic.com

billdenney and others added 9 commits October 6, 2026 22:20
Quarto 1.9 no longer sets the QUARTO_VERSION environment variable in the
R process it renders with, so is_quarto_render() returned FALSE under
Quarto: the ggtibble chunk option stopped prefixing fig- to its labels
and stopped using fig.subcap for multiple captions. Quarto still sets
the knitr package option quarto.version, which knitr's own Quarto test
reads, so check that as well as the environment variable.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
ggtibble() gains `footnote` and `label` arguments, glue specifications
evaluated per row with the same glue_data() call as `caption`, giving
`footnote` and `label` columns that are empty when not given.
new_ggtibble() adds both columns as empty strings when absent, so
as_ggtibble() from a gglist gets them too, and it refuses labels that
repeat or that use characters other than letters, digits, hyphens,
underscores, and dots, with classed errors naming the offenders.
An outercol used only in `footnote` or `label` no longer triggers the
unused-outercols warning.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A ggtibble with a footnote or a label on any row is now written by
knit_print() as markdown, one figure at a time, so each figure carries
its own identifier and its footnote stays with it: knitr's plot hook
can give neither. One emitter serves every engine:

- LaTeX (R Markdown and Quarto): the footnote is inside the float,
  after the caption, a line break, and in \footnotesize, with the plain
  caption as the short caption for the List of Figures; the label is
  the \label{}. Under Quarto a fig- labelled figure is a figure Div with
  fig-scap; otherwise the float is written as raw LaTeX around the
  caption markdown so pandoc still converts it.
- Quarto to Typst: the figure Div and then the footnote in 0.9em text,
  both in one #block(breakable: false), as nca.reporter's
  report_print_figure() does; the footnote stays outside the Div so
  Quarto still treats the Div as a cross-referenceable figure.
- HTML: a figure-footnote Div in a smaller font after the figure.
- Word, other pandoc formats, and knitr markdown: a plain paragraph.

Images are saved under the chunk's fig.path with its dev, fig.width,
fig.height, and dpi, named after the label when there is one. Under
Quarto an unlabelled figure gets fig-<chunk label>[-<row>], so each row
is its own numbered figure. The chunk needs results = "asis": the
ggtibble chunk option sets it for an annotated ggtibble (and leaves
fig.cap, fig.subcap, and the fig- chunk label off, since the figures
carry their own ids), and knit_print() in a chunk without it is a
classed error. A ggtibble without footnotes or labels takes the old
path unchanged.

knit_print.gglist()'s fig_suffix and filename handling move to helpers
that the emitter reuses, and knitr::raw_block() and knitr::fig_path()
build the raw fences and image paths.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
ggsave() on a ggtibble with no `filename` now names each file
<label>.<device>, with "png" when `device` is NULL, in `path` (the
current directory by default). Every row needs a label, and `device`
must be a string so that it can serve as the extension; either missing
is a classed error.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Regenerate the man pages (roxygen2 8.1.0 also updates its version
field in DESCRIPTION), add a "Footnotes and labels" section to the
introduction vignette with a rendered example, add the NEWS entries
under a new development version heading, bump the version to
1.0.4.9000, and add Typst, pandoc, and subfigure to the word list.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ment

Review fixes for the footnote and label emitter:

- A caption is the bracketed text of a pandoc image in R Markdown HTML,
  Word, and other pandoc output, so an unbalanced bracket such as
  "AUC over (0, 24] h" broke the image and lost its id. Unbalanced
  brackets and a trailing backslash are now escaped (balanced brackets,
  as in a link, pass through), captions are joined onto one line, and
  image paths are written as <path> so spaces or parentheses cannot
  break them. The Quarto figure Div's caption paragraph is joined onto
  one line too.
- Image files are now <fig.path><chunk label>-<label>, so the same
  labels in two chunks no longer write one image over the other, and
  figures of one chunk that would share a file (labels differing only by
  case, or a label equal to another row's number) are a classed error.
- A figure id already written by an earlier chunk of the document is an
  error (ggtibble_error_label_duplicated) naming both chunks. Ids are
  tracked per knitr::knit() run, found from its frame on the call stack,
  so a run that stopped with an error does not leave ids behind; the
  document hook also clears them.
- Labels that differ only by case are duplicates, since they name the
  same file on Windows and macOS.
- Under Quarto, labels without the fig- prefix give one classed warning
  per chunk (ggtibble_warning_label_not_fig), since Quarto reads @Label
  for them as a citation.
- A derived id that clashes with a label now says it was derived from
  the chunk label.

The render helpers shared by the test files move to helper-render.R.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The test asserted that "Unable to resolve crossref" was absent from the
HTML, but Quarto writes that only to the console, and its "fig-my_plots"
match was satisfied by the unresolved "?@fig-my_plots" text, so it
passed while the fig- prefix was missing. It now asserts the figure
container id, a subfigure per caption, and a resolved quarto-xref link,
and it loads this source tree in Quarto's R process when run from
source. A unit test pins the fig- prefix when Quarto is detected only
from knitr's quarto.version option set to 1, as Quarto 1.9.37 sets it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The rendering table now says which outputs keep the footnote with its
figure (LaTeX and Typst do; Word does not, and its footnote is in the
body text size), that captions and footnotes are markdown (a leading
"# " makes a heading, raw LaTeX reaches only LaTeX output), which chunk
options the footnote and label route uses (fig.path, label, dev,
fig.width, fig.height, dpi, fig.pos) and which it does not apply
(out.width, out.height, fig.align, fig.alt, fig.cap, dev.args), and the
per-document id rule and chunk-prefixed image names. NEWS and the
vignette match. knitr is now required at 1.31 or later, the release
that exported pandoc_to(); raw_block() dates from 1.21.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…y from pandoc 3.8.3

The coverage workflow had no setup-pandoc step, so it ran the Ubuntu
runner's pandoc 3.1.3, which writes no bookmark for a figure id in a
Word document; the check workflows install a current pandoc. The Word
test now expects the bookmark only when pandoc is at least 3.8.3, the
oldest version verified to write it, and matches the tag however it is
serialized.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@billdenney
billdenney merged commit 18e8355 into main Oct 7, 2026
9 checks passed
@billdenney
billdenney deleted the feat/footnote branch October 7, 2026 12:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant