Feat: Add tags which can be provided on each theorem instantiation an…

[marc-thieme]

This PR adds a tags field to the numbering attachment of the theorem figures. For each instance of a theorem by the document author, they can provide a list of named tags the want to attach to the theorem. These tags will be available to the styling function through params.tags..
I would still need to add tests and some documentation for discoverability of the feature. But before that, I would like to know if you would be open to merging this feature:

Use case for the feature

When each instance of a theorem in your document needs instance-specific metadata to be styled correctly.
For example, I recently prepared for an exam and compiled a collections of theorems we needed to know. I wanted to annotate my theorems with the exam that they were questioned for. The only way this was really possible was by jumbling them up into the name attribute, which was very limiting.

Note this example using my proposed implementation.

#let custom-styling(thm) = {
  let params = lemmify.get-theorem-parameters(thm)
  let number = (params.numbering)(thm, false)
  params.name
  h(1fr)
  params.kind-name + " " + number
  h(1fr)
  params.tags.exam
  block(params.body, stroke: yellow, inset: 0.8mm)
}
#let (theorem, theorem-rules) = lemmify.default-theorems(style: custom-styling, tags: (exam: "all exams"))
#show: theorem-rules

#theorem(name: "Eulerian tour", exam: "WS19")[
  A graph contains an eulerian tour iff the degree of each vertex is even
]

The code relies on knowing the theorem name and the exam separately, so it can inject the theorem in between them.

Design and considerations

The proposal at hand:

• For each specific theorem instance invocation, the author can provide more named arguments.
• These named arguments must be declared before. In the theorem-kind function, you may now provide a dictionary of allowed tag values and default values for them.

Possible alterations and their downsides:

• Strong typing: The dictionary doesn't provide default values but a list of allowed types. However, this would yield a too cumbersome api because a defintion like theorem-kind(..., tags: (exam: (content, str, array), ...) would clutter code. Also, this is more in line with the (lack of) typing in function signatures
• Allow positional tags: Feels brittle, would add complexity to the code, don't know how this behaves with the body as positional argument, etc.
• Add requiered tags without a default value: The selection code assumes default-constructible theorems. This would have to be worked around when the theorems require tags to be provided. Also, then these classes would not be compatible with theorems defined in old code (without the required tag). They would live in another paradigm/class. Might be inconvenient.

The implementation at hand is the most conservative one imo

[Marmare314]

Thanks for the PR! I think allowing custom arguments to be passed to the styling function definitely makes sense (I thought I already added this, but apparently I did not). By that I mean extending create-theorem with an argument sink (probably only allowing named arguments as you suggested) and just passing them along to the styling function.
What I'm not so sure about is adding a specific argument like "tags", as to me it looks quite specific to your use-case. But with the above approach this should be reasonably simple to implement.

Also I'm not sure when/if I want to release this refactored version since I'm still not quite happy with how it turned out (see #23), and I want to avoid too many breaking changes. Unfortunately adding this feature to main is probably not possible.

[marc-thieme]

I completely understand. I also agree that the tags field is too specific of an idea to add core–support for it. However, I would argue that some means of funneling custom arguments from the call site through to the styling function would be helpful.
In my implementation of the idea for example, the custom styling–function receives a parameter custom-arg which must be provided when initializing a theorem–kind but can also be overridden for each instance of a concrete theorem–block in the document.