Add user customization, documentation, and benchmark

[quachpas]

Hello there!

I've been sitting on my fork of glossarium and decided to finally do something :). Thanks for all the amazing work you've done.

I realize I've written quite a bit, but I'll summarise below and I am obviously open to feedback!

Summary

• User customization: I split the print-glossary function into multiple parts in order to expose a user customization interface. See documentation below for details (or the code).
• Partial Documentation
• just benchmark using https://github.com/sharkdp/hyperfine

Details

Details

• All user customization interfaces are prefixed with user- (I haven't found anything better yet). If someone has a better idea, please share!
• All default behaviour is implemented in functions with prefix default-
• rename attribute desc to description: I feel like the more attributes we add, the less clear it will be for the user which shorthand is supposed to be which ... IMO we should strive to write complete names, although that's up to debate.
• replace flag enable-group-pagebreak by user customization user-group-break. The default behaviour is () => [] (nothing). Users can specify which break they want in this way print-glossary(..., user-group-break: pagebreak) or colbreak or any () => content
• Added another default label (see default-print-reference and make-glossary) of the form key:pl to reference plural forms directly.
• Added user getters for attributes of an entry, that may or may not be returned as a link, see gls-key, gls-short, etc.
• Added library variable glossarium_version to expose the package version to the user and in error messages. Added to tbump.
• Refactor error messages into developer function __error_message(msg, kind) with kind specific error types to dispatch error messages
• Refactor key gets into __get_entry_with_key with try/panic loop
• Refactor conditions, see __is_first_or_long, __has_attribute, has-long, has-longplural, etc.
• Refactor glossarium's link+label into __link_and_label
• Rename variables, "private" variables are "__snake_case", others are "kebab-case"
• FIX: If a group's entries have no references, do not print the group heading (see default-print-glossary and count-refs)
• FIX: query the previous heading level and print group headings as level: n+1 instead of level: 2
• FIX: If the build step fails in just build-examples, then find fails as it does not find files to delete. Fixed by removing the find -delete.
• Added benchmark using hyperfine.
• Added tests/debug.typ to help in debugging during development.

benchmark

This PR reduces performance. I am not sure how it scales with large glossaries. I don't think it's a huge issue as of now, as typst is just ... blazing fast.

Details

This branch

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
typst compile --root . examples/full-example/main.typ	35.2 ± 1.4	32.8	41.8	2.42 ± 0.14
typst compile --root . examples/groups/groups.typ	17.3 ± 0.5	15.8	19.1	1.19 ± 0.07
typst compile --root . examples/import-terms-from-yaml-file/main.typ	14.5 ± 0.6	13.3	17.7	1.00
typst compile --root . examples/plural-example/main.typ	17.6 ± 1.0	16.1	22.4	1.21 ± 0.09

v0.4.0

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
typst compile --root . examples/full-example/main.typ	25.8 ± 0.6	24.3	27.8	1.97 ± 0.09
typst compile --root . examples/groups/groups.typ	16.3 ± 0.5	15.1	17.5	1.24 ± 0.06
typst compile --root . examples/import-terms-from-yaml-file/main.typ	13.1 ± 0.5	12.1	15.8	1.00
typst compile --root . examples/plural-example/main.typ	16.3 ± 2.5	14.5	45.7	1.25 ± 0.20

[slashformotion]

Thanks for your work, I am on holiday currently. I will review when I get back.

[slashformotion]

Overall, a welcomed refactor. I look forward to hearing from you about the specific points mentioned in the review. I don't claim to hold the truth here; I am open to discussion about how glossarium should evolve

[quachpas]

Hello @slashformotion, thanks for the review! I I answered your comments above! hopefully that answered your questions.

About the evolution of glossarium,

• the refactor helps other contributors see more clearly in the code (hopefully)
• the user customization would open the doors to more technical users who'd like to change things without having to have a local version of glossarium

I can imagine a subsequent PR to add different styles other than the default one like glossaries and glossaries-extra to have an easy switch, see https://www.dickimaw-books.com/gallery/glossaries-styles/.

[slashformotion]

I will fix the merge conflicts and merge locally if you don't want to rebase.

[quachpas]

I will fix the merge conflicts and merge locally if you don't want to rebase.

I'll take a look tomorrow and rebase, thanks!

[slashformotion]

@quachpas if you are interested in glossarium development, please join this discord server https://discord.gg/K3sdEGZd .
The goal is not to create a huge server, only for the contributors who want to coordinate the development efforts.

[quachpas]

@quachpas if you are interested in glossarium development, please join this discord server https://discord.gg/K3sdEGZd . The goal is not to create a huge server, only for the contributors who want to coordinate the development efforts.

I personally dislike using Discord for software dev ... I'd rather not join. Is there no plan to just use GitHub? or a dev mailing list?

[slashformotion]

I don't have a strong opinion on where the discussions around software dev should happen. We could use the discussion feature on github. I have never used mailing lists so there's that

[quachpas]

Maybe we can open a pinned issue "Roadmap 0.5.0" where people can discuss?

[quachpas]

Should be good to go @slashformotion