Add support for PDF/UA-1

[Andrew15-5]

Closes #113.

My first approach was to provide all the missing alt text, which was really not something someone would wanna read anyway. And so I discovered pdf.artifact through @xkevio. And it definitely falls under the decorative images for the two bottom images, but for the rest... There is no mention of figure hacks, but since they are invisible and all, I guess it makes more sense to convert all figures into artifacts as well.

Tested with

#import "@preview/codly:1.3.1": *
#show: codly-init

#set document(title: "Title")

#codly(
  reference-by: "item",
  highlights: ((line: 1, start: 1, label: <this>, tag: [a]),),
  // highlights: ((line: 1, start: 1, label: <this>),),
)
#figure(
```typ
$x = y$

$y = b x + m$
```
, caption: []
) <label>

@label:1

@this

@label

#figure(
```typ
$x = y$

$y = b x + m$
```
, caption: []
) <another>

Not sure if text of a language should be omitted. Of course, it's not 100% certain the code with this package is a one single thing or not, compared to the default, but either way, reading the language name might be very useful, though would be strange if there are no references to it in the text.

The docs use figures/images, IIRC, so this does not make them PDF/UA-1 compatible, since it's not part of the package.

[Andrew15-5]

As was mentioned in the Documentation thread, it appears that text-based figures (and apparently also raw.line, so everything but image?) do not require alt. However, I noticed that there is a no-highlights option:

codly/src/lib.typ

Lines 497 to 508 in 9e8e243

	return [#figure(
	kind: "codly-line",
	supplement: none,
	caption: none,
	outlined: false,
	numbering: (..) => {
	ref(block-label)
	reference-sep
	reference-number-format(it.number)
	},
	l
	)#lab]

highlight option:

codly/src/lib.typ

Lines 694 to 703 in 9e8e243

	return [#figure(
	kind: "codly-line",
	supplement: none,
	numbering: (..) => {
	ref(block-label)
	reference-sep
	reference-number-format(it.number)
	},
	l
	)#lab]

and a general thing:

codly/src/lib.typ

Lines 1601 to 1613 in 9e8e243

	let l = pdf.artifact(figure(
	kind: "__codly-raw-line",
	numbering: none,
	placement: none,
	outlined: false,
	gap: 0pt,
	caption: none,
	[#raw.line(
	line.number + offset,
	line.count,
	line.text,
	box(height: height, width: 0pt) + line.body,
	) <codly-highlighted>]

The first two can be caught with the provided test. If you add highlight for a code block, the second snippet is used, if no highlights — first one is used. But the last one affects both, and I get...

error: PDF/UA-1 error: missing alt text
    ┌─ @preview/codly:1.3.1/src/lib.typ:497:15
    │
497 │         return [#figure(
    │ ╭────────────────^
498 │ │         kind: "codly-line",
499 │ │         supplement: none,
500 │ │         caption: none,
    · │
507 │ │         l
508 │ │       )#lab]
    │ ╰───────^
    │
    = hint: make sure your images and equations have alt text

So...it actually propagates to the inner snippet for no highlights. Wrapping that in pdf.artifact causes this general one to just work. I.e., you either wrap the artifact around the no-highlights one, or this global one, but at least one must be wrapped.

This tells me that alt is in fact required for everything other than text, non-empty sequence, raw, and styled. It doesn't work for empty sequence and space, including raw.line. Reference to typst/typst#7487.

#figure([text], caption: [])
#figure([a --- b], caption: [])
#figure(text(red)[a --- b], caption: [])
#figure(`raw`, caption: [])
#figure(caption: [], ```
raw
block
```)

Since I don't see any relevant documentation to all this (in lib.typ), I'm not sure what to do. IIUC, all 3 places must not have artifact wrappers, since it will hide the source code text from AT. And the whole point is to make the package better for AT use. The other places should keep the added artifact wrappers.

[Dherse]

Thank you, please note I will be adding it in dev-v1.4.0 directly, I'll try to add you as a commit author on it.

[Andrew15-5]

I see a few related commits now. Did you intent to add Co-authored-by?

[Dherse]

I will indeed, but I'll probably do one big "co-authors" commit at the end of the PR with everybody involved :)

[Dherse]

I will close this in the meantime. The commit with all co-authors will come before I go and work on the new docs (likely a gh.io website now). Thank you for taking the time! I did use your solution. It'll be in #141.