Export target elements

[tingerrr]

Description

I propose adding document-like set-rule only elements for export targets to control target specific settings:

• png
  • controlling PPI from within Typst documents
    • although this may open a small DOS attack surface from template packages choosing astronomical values
• pdf
  • PDF document metadata, which is currently set using document

Use document either for only the common settings or as a convenient default for various settings from multiple targets.

Alongside this, a variable such as target should be added, which is set depending on the current export target. This allows code to act according to the export target, preventing incorrect output or panics when a target specific feature is used, such as Forms #2421 or OCGs #2613.

The newly added elements and variable could be put into an export module, i.e. set export.pdf(...), if export.target == export.pdf { ... }, as they should not require easy access for the majority of users.

While I thought about the target variable being the element of the active export target for nice looking checks (target == pdf), this comes with some downsides:

• elements with no fields must be available too (svg)
• sub-targets, such as PDF/A-2 support #2942 are not easily accounted for unless they receive potentially useless sub-elements like pdf.a2 or pdf.x
• if sub-elements are added, they would complicate the simple checks as the equality would no longer hold target == pdf would be false for target == pdf.a2, users would need to use target in (pdf, pdf.a2, pdf.x), listing all possible sub-targets

Using strings solves this more easily, as these sub-target checks could use string methods like target.starts-with("pdf") or even target.starts-with("pdf/a") for all versions of PDF/A.

Most of the sub-target specific settings will likely live on the "encompassing" element anyway (i.e. pdf for PDF/A).

Use Case

1. Export target specific features which are likely to be more "low-level" than normal Typst features if they can't be easily generalized will likely need packages to be made usable for the average Typst user.

   Such packages need to be able to:

   • use export target specific features without panics (if they do when used on an unsupported target)
   • provide reasonable fallback behavior, when the target specific feature is not supported
     • this is especially important for preview of features which are not available for PNGs, such as forms
     • provide example images of target specific features without the need to take screenshots of PDF viewers to show of export target specific packages

2. Export targets such as HTML HTML Export #721 likely need more export target specific code, as it is fundamentally different from how Typst currently works.

[emilyyyylime]

target sounds like it'd fit inside the sys module, but I'm not too against export either

[laurmaedje]

I think the question of a target variable and elements for setting target-specific metadata is fairly separate.

I want to have a target variable (and I agree that sys would be a good place for it), but I'm not sure how fine-grained it should be, e.g. whether we should make it possible to distinguish SVG and PNG. Potentially, it could be a type with a few methods like is-html() and is-pdf() rather than a enum or a string. However, it also feels a bit over-engineered and unnecessarily complex. Maybe there isn't much extra harm in allowing SVG and PNG to be distinguished as well.

As for the target-specific metadata: I see how adding it all to document is not great, but I'm not sure configuring the DPI for PNG from within Typst is really necessary. To me, it seems just like the other command line flags, which are also not configurable from within Typst (which is a separate story and maybe not for all of them great, but allowing specifically DPI just because it is target-specific feels strange).

I would prefer to get some experience with target-specific things with target and forms before settling on a design for target-specific metadata.

[tingerrr]

To me, it seems just like the other command line flags, which are also not configurable from within Typst (which is a separate story and maybe not for all of them great, but allowing specifically DPI just because it is target-specific feels strange).

Yeah, to be completely honest, it probably only serves as an example of things that one may want to control for other output formats. Since I haven't really touched SVG at all, yet I wouldn't know if there is anything for that and for PNG this is the only thing that seemed similar to PDF specific metadata. It will probably be more relevant for HTML.

I would prefer to get some experience with target-specific things with target and forms before settling on a design for target-specific metadata.

Somewhat understandable, but it does impose something on PDF forms, namely that they must always be exported at this moment if there is no way to turn them off conditionally. But maybe their implementation will help in exploring the right API.

[laurmaedje]

Somewhat understandable, but it does impose something on PDF forms, namely that they must always be exported at this moment if there is no way to turn them off conditionally.

I don't follow. Wouldn't a sys.target allow us to do that? My comment was only about the set pdf(..).

[tingerrr]

I don't follow. Wouldn't a sys.target allow us to do that? My comment was only about the set pdf(..).

Oh, pardon me, I misunderstood.