search

typst-community / glossarium

Glossarium is a simple typst glossary.
MIT License
41 stars 11 forks source link

Add user customization, documentation, and benchmark #37

Closed quachpas closed 6 months ago

quachpas commented 6 months ago

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

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 commented 6 months ago

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

quachpas commented 6 months ago

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

About the evolution 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 commented 6 months ago

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

quachpas commented 6 months ago

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 commented 6 months ago

@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 commented 6 months ago

@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 commented 6 months ago

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 commented 6 months ago

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

quachpas commented 6 months ago

Should be good to go @slashformotion