feat(outputters): Expose writing of PDF resources to Lua

[Omikhleia]

(It's the minimal C part of #2251)

This commit extends the low-level C wrapper to libtexpdf to let Lua code add page resources directly to the PDF. This makes it possible to prototype extensions to the Lua outputter without recompiling SILE, and opens the door to features such as gradient support.

EDIT: Now in may 2026 I have more understanding than in August 2025... Proposal amended:

• pdf.add_page_resource
• get_page_resources
• add_page_annotation

See comment further below.

[Omikhleia]

Removed 0.15.14 milestone (switched to 0.x.y):
There's potentially a way to do this without extending our Lua C bindings, with lower-level libtexpdf construct (as I did in resilient.packages.forms and resilient.packages.attachments) -- I might experiment with it, and this PR is perhaps not needed.

[Omikhleia]

There's potentially a way to do this without extending our Lua C bindings, with lower-level libtexpdf construct (as I did in resilient.packages.forms and resilient.packages.attachments) -- I might experiment with it, and this PR is perhaps not needed.

Having experimented, it is needed.
libtexpdf handles most page-related dictionnaries via internal variables (here, currentpage->resources).
The (quite ugly) trick I used resilient.packages.forms¹ cannot work here, as the Resources dictionary is always reset by the library (when creating and updating it for font references, etc.).
So any attempt creating and modifying it from Lua won't work, it's cleared by libtextpdf's logic.
The Resources are indirect references after the page is shipped out, so we cannot either access them in an ouputter hook (e.g. just after the pdf.endpage calls. Here we can access it, but only get an indirect object, and we don't have low-level methods to de-reference it).

Footnotes

1. EDIT -- libtexpdf also handles the annotation dictionary in internal variables (page->annots), but it only resets it when texpdf_doc_add_annot is called -- in our case, via pdf.end_annotation used for hyperlinks. The dirty trick consists in bypassing that call and manually creating the annotation entries from Lua. It's not nice, but it works.
   For resources, however, they are used for lots of things (fonts, proc sets, etc.) and there's no way to bypass that. (I don't know if I am very clear here...).
   Would we want to also get rid of the annotation trick, we'd need for instancepdf.add_dict to accept as argument both a string (as it currently does) or a userdata (built from Lua with nested references etc.) EDIT: Or a dedicated C call for adding annotations, similar to the method for adding ressources. ↩

[Omikhleia]

Revisited my old PR and made it better.

The new constructs are planned to be used here

• Removing the dirty hack in resilient.forms to play well with links
• Adding gradient support

The latter is (at this day) still experimental, and needs extra support in my "framebox" package (amongst others), and the underlying "grail" drawing layer -- but the basic steps and first results can already be seen in the aforementioned PR.