Control element properties

[fleimgruber]

Follow-up on #26 (comment):

For example, the width of a figure could be controlled via a line #+ATTR_TYPST as in

#+ATTR_TYPST: :width 600
[[./figure.svg]]

which would export to

#figure([#image("figure.svg", width: 600)])

in a similar way as is done for LaTeX export.

[idlip]

Hey. I recently started using typst, and ox-typst adds good basic support for it.

As I was exploring, I believe that typst syntax is so easy and straight forward simple to understand.

So I was wondering, about #+attr_typst: too

IMO I thought rather ox-typst doing for org convenience, it should let attr_typst be a space filling form for the object (image, table, heading...)

For eg:

#figure(
  image("glacier.jpg", width: 80%),
  caption: [A curious figure.],
  numbering: "1.a",
  gap: 0.5em
) 

#+attr_typst: caption: [A curios figure.], numbering: "1.a", gap: 0.5em

Since it can be very straightforward and should be as replacable component inside figure

#figure(image(...), %s) %s -> is from #+attr_typst:

similarly this can apply to heading as well.

#+attr_typst: level: 2, outlined: "false"
* Introduction

This method for now will allow customization for various functions, without needing to use much of #+typst: or #+being_export typst for custom type settings.

To add more we can add replacement for placement text as well, to adjust font size, style and tweak title or content part.

#+attr_typst: level: 2, :content text(fontsize: 15pt)

I believe that ox-typst package should not have more hacky way of implementing options just for convenience of org, it can stay simple and focus on other hard issues. IMHO typst is so easy to learn.
If typst documentation can be downloaded as an info file, then that will solve most of the beginners issue.
I hope you get my point, if not please allow me to explain again.

[jmpunkt]

Thanks for the input. The current implementation (#32) requires each Typst element to know their supported elements. They can consume known attributes and ignore unknown. This has the downside that new version of Typst require ox-typst to support the new attributes. However, newer versions of ox-typst will work with older versions of Typst.

The problem with your idea are mainly nested structures. For example, tables are wrapped inside a figure. These two Typst elements are generated by the same Org element. Therefore, they share the same attributes. If you just paste these attributes inside the element, then you can only support one element at a time. As a result, we can not specify attributes for the figure and table at the same time.

There is another issue. Since we do not know about the attributes, we might introduce duplicates. For example, Org has the attribute #+caption. When you also specify a caption with #+attr_typst, then you have a duplicate. Specifying the same argument twice within Typst is not possible and throws a compilation error.

If Org does supports something (e.g. captions), then we have to translate this. attr_typst should only be used when there is no way of specifying this in Org.

I wonder if we should introduce special arguments in the form of special-<TYPST-ELEMENT>. The user can use this to bypass everything and write directly into the element function, similar to your proposal.

#+ATTR_TYPST: :special-figure ", one-more-attribute-trust-me: 1px"

But I am not sure if we need this and the Syntax seems ugly.

I guess for now there is no better way to express these constraints, other than knowing about the arguments in advance.

[fleimgruber]

Thanks for the explanations.

The special-... approach would be one way to do it, but I agree it seems a bit odd and too special.

I guess for now there is no better way to express these constraints, other than knowing about the arguments in advance.

Are you referring to a workaround or a way to make it work today? If so which one would it be, I am not following this.

[jmpunkt]

I guess for now there is no better way to express these constraints, other than knowing about the arguments in advance.

Are you referring to a workaround or a way to make it work today? If so which one would it be, I am not following this.

I partly implemented it such that we know about the attributes (#32, not merged yet). You can checkout the supported attributes and their elements here and how it's used.

Alternative

Another way of implementing this, would be prefixed attributes. For example figure-outline: .... This has the advantage, that the target for the attribute is clear. There might be also an issue with the non-prefixed approach regarding new attributes. Currently there should is no overlap between the attributes of the different Typst elements. But imagine if figure and image have the same attribute with a different type in the future. Then the non-prefixed approach would fail. Since image and figure are generated by the same Org element, they share the same attributes list. We could not differentiate where the specified attribute should be applied to. The prefixed approach would not have this issue.

We could also forward unused attributes, which are not filled by us. For example, every argument with figure-*: ... is forwarded to the figure element. We would filter attributes like caption, since it can be provided through Org. The implementation still has to know about attributes used by Org (e.g. caption in figure can be specified through Org), but future attributes could be used without an update.

The prefixed approach has a better user experience regarding future compatibility and clarity. However, it would require the user to write more text. So I am not sure if we should take this approach.

[fleimgruber]

As a user, I value compatibility and clarity more than non-verbose APIs, so would vote for a prefixed attributes approach. Would be great to get other user opinions on it, so that you can make the appropriate dev decision.

I would even say that in an experimental state (i.e. version 0.x) you are free to have breaking changes and could go with #32 and revise later if prefixed attributes turn out to be better.

[filipencopav]

There is another issue. Since we do not know about the attributes, we might introduce duplicates. For example, Org has the attribute #+caption. When you also specify a caption with #+attr_typst, then you have a duplicate. Specifying the same argument twice within Typst is not possible and throws a compilation error.

It might be possible to make a "priority hierarchy". For example if some #+attr_typst attribute has the same meaning semantically as #+caption or some other org mode thing, we might say that it has lower priority than the #+caption, and therefore if there is also a #+caption value, then that will be used instead of the value specified in #+attr_typst. Please ping me later this week so I remember to go through the code and maybe submit a PR to do something like this.

[jmpunkt]

It might be possible to make a "priority hierarchy".

That is definitely possible. I am just wondering if it is worth. I would rather a single configuration option (built into Org) rather than have a hacky way with #+attr_typst. The current implementation (#32) adds keywords for every argument which are not covered by the built-in functions. Is there a use case where want to specify, e.g. the caption, via the #+attr_typst rather than #+caption?

Issue Tables

Another issue I came across during the implementation are tables. Typst allows to heavily customize cells (https://typst.app/docs/reference/model/table/#definitions-cell). We probably also want to customize them. The question is: how do we specify attributes for cells, columns, and rows. Or should that even be possible? We could easily apply the arguments to all cells, by looking up the parent table and its attributes.

On Named Attributes

Your idea with priority hierarchy gave me an idea. If we prefix every argument with its target element (e.g. figure-gap), then we could specify the attribute at the section level and every figure within that section would use the same gap. We would collect all arguments of our parents, their parents, and so on. Not sure how useful this is, or if the hierarchy of Org even allows this in a meaningful way. However, some attributes would be still meaningless, e.g. figure-caption on the section level, it does not make sense to have the same caption for all figures.