Fix tagpdf alt text warning parsing and improve guidance

- Fix regex in parse-error.ts to handle tagpdf line continuations when
  filenames are long (the warning wraps across multiple (tagpdf) lines)
- Update warning message to recommend fig-alt instead of caption-as-alt
- Add printsMessage check to caption-not-alt-ua test to verify the
  missing alt text warning is surfaced
- Use labeled figure in caption-not-alt-ua test to avoid unrelated UA-2
  structural nesting issue with unlabeled figures
- Add ua2-unlabeled-figure-caption test documenting known LaTeX/tagpdf
  limitation where unlabeled captioned figures produce <Caption> directly
  under <Document> instead of inside a grouping element

Author: gordonwoodhull

src/command/render/latexmk/parse-error.ts

@@ -125,8 +125,10 @@ export function findPdfAccessibilityWarnings(
 
   // Match: Package tagpdf Warning: Alternative text for graphic is missing.
   //        (tagpdf)                Using 'filename' instead.
+  // Note: tagpdf wraps long filenames across multiple (tagpdf) continuation
+  // lines, so we allow optional line breaks with (tagpdf) prefixes.
   const altTextRegex =
-    /Package tagpdf Warning: Alternative text for graphic is missing\.\s*\n\(tagpdf\)\s*Using ['`]([^'`]+)['`] instead\./g;
+    /Package tagpdf Warning: Alternative text for graphic is missing\.\s*\n\(tagpdf\)\s*Using ['`]([^'`]+)['`]\s*(?:\n\(tagpdf\)\s*)?instead\./g;
   let match;
   while ((match = altTextRegex.exec(logText)) !== null) {
     result.missingAltText.push(match[1]);

src/command/render/latexmk/pdf.ts

@@ -204,7 +204,7 @@ async function initialCompileLatex(
       if (accessibilityWarnings.missingAltText.length > 0) {
         const fileList = accessibilityWarnings.missingAltText.join(", ");
         warning(
-          `PDF accessibility: Missing alt text for image(s): ${fileList}. Add alt text using ![alt text](image.png) syntax for PDF/UA compliance.\n`,
+          `PDF accessibility: Missing alt text for image(s): ${fileList}. Add alt text using fig-alt in YAML or {fig-alt="description"} on the image for PDF/UA compliance.\n`,
         );
       }
       if (accessibilityWarnings.missingLanguage) {

tests/docs/smoke-all/pdf-standard/caption-not-alt-ua.qmd

@@ -19,6 +19,11 @@ _quarto:
         - ['\\DocumentMetadata\{', 'pdfstandard=\{ua-2\}', 'tagging=on']
         - # Caption must NOT appear as alt text on \includegraphics
           ['includegraphics\[.*alt=']
+      printsMessage:
+        # tagpdf warns about missing alt text and falls back to filename;
+        # Quarto surfaces this as a user-facing warning
+        level: WARN
+        regex: "PDF accessibility:.*Missing alt text"
     typst:
       # Typst's own PDF/UA enforcement errors on missing alt
       shouldError: default
@@ -29,4 +34,8 @@ _quarto:
 A figure with a caption but no explicit `fig-alt`.
 The caption should NOT be copied into alt text.
 
-![This is a caption, not alt text](penrose.svg)
+Uses a cross-ref label to go through FloatRefTarget, which produces
+valid UA-2 structure. See `ua2-unlabeled-figure-caption.qmd` for the
+known structural issue with unlabeled captioned figures.
+
+![This is a caption, not alt text](penrose.svg){#fig-test}

tests/docs/smoke-all/pdf-standard/ua2-unlabeled-figure-caption.qmd

@@ -0,0 +1,47 @@
+---
+title: "UA-2: unlabeled figure caption produces invalid structure"
+lang: en
+format:
+  pdf:
+    pdf-standard: ua-2
+    keep-tex: true
+_quarto:
+  tests:
+    run:
+      # verapdf validation not available on Windows CI
+      not_os: windows
+    pdf:
+      noErrors: default
+      ensureLatexFileRegexMatches:
+        - ['\\DocumentMetadata\{', 'pdfstandard=\{ua-2\}', 'tagging=on']
+        - []
+      printsMessage:
+        # Known issue: unlabeled captioned figures go through pandoc3_figure.lua
+        # which produces a bare \begin{figure}[H] environment. LaTeX's tagpdf
+        # places <Caption> as a sibling of <Figure> under <Document> instead of
+        # nesting them inside a grouping element. This violates UA-2 which
+        # requires <Caption> to be a child of <Figure>, <Table>, or <Formula>.
+        #
+        # Labeled figures ({#fig-label}) go through FloatRefTarget, which wraps
+        # the figure in a \Div that provides the grouping context tagpdf needs.
+        #
+        # Structure produced (invalid):
+        #   /Document
+        #     /Caption    <- should be inside a grouping element
+        #     /Figure     <- sibling instead of parent
+        #
+        # Expected (valid, as produced by labeled figures):
+        #   /Document
+        #     /Div
+        #       /Caption  <- properly nested
+        #       /Figure
+        level: WARN
+        regex: "PDF validation failed for ua-2"
+---
+
+# Known LaTeX tagging limitation
+
+An unlabeled captioned figure produces invalid UA-2 structure because
+tagpdf does not nest `<Caption>` inside a grouping element.
+
+![This is a caption on an unlabeled figure](penrose.svg)