diff --git a/packages/preview/glossarium/0.5.3/CHANGELOG.md b/packages/preview/glossarium/0.5.3/CHANGELOG.md new file mode 100644 index 000000000..a016b8f96 --- /dev/null +++ b/packages/preview/glossarium/0.5.3/CHANGELOG.md @@ -0,0 +1,177 @@ +# Changelog + +## 0.5.3 + +> [!IMPORTANT] +> `glossarium@0.5.3` is compatible with Typst>=0.13.0. + +> [!WARNING] +> `glossarium` internals have changed to use `figure.body` instead +> of `figure.caption`. If you have custom show rules, please change accordingly. + +## 0.5.2 + +> [!TIP] +> A new option `use-key-as-short` has been added and is enabled by default +> on `register-glossary`. This option allows writing new entries without +> specifying the `short` field. The `key` field will be used as the `short` +> field. If you want to disable this behavior, you can set the option to `false`. +> ```typ +> #entry-list = ( +> ( +> key: "key", +> ), +> ) +> #register-glossary(entry-list, use-key-as-short: true) +> @key +> ``` + +> [!TIP] +> Glossarium will now panic if you haven't called `make-glossary` before +> `print-glossary`. + +> [!TIP] +> Glossarium now panics if you try to register an entries with +> unknown fields. + +> [!IMPORTANT] +> Fix layout divergence when glossary descriptions are nested. + +> [!NOTE] +> - Fix an issue where backreferences were queried on the whole document, +> instead of before `print-glossary`. +> - Fix a regression for versions of Typst before v0.12.0 where `it.body` was +> returned instead of `it.caption` for `make-glossary`. + +## 0.5.1 + +> [!TIP] +> New group options have been added: `print-glossary(groups: array)` to +> display only the specified groups. +> ```typ +> #print-glossary( +> // ... +> groups: ("Group A", "Group B", "") // "" is the default group +> ) +> ``` +> and `print-glossary(group-heading-level: int)` to set the heading level for +> groups regardless of the previous heading level. +> ```typ +> #print-glossary( +> // ... +> group-heading-level: 3 +> ) +> ``` + +> [!TIP] +> A new parameter `print-glossary(minimum-ref: int)` has been added to filter +> entries with a minimum number of references. +> ```typ +> #print-glossary( +> // ... +> minimum-ref: 2 +> ) +> ``` + +> [!TIP] +> New counting functions have been added: `count-all-refs` and `there-are-refs` +> in addition to `count-refs`. +> ```typ +> #context count-all-refs() +> #context if there-are-refs() [ +> = Glossary +> ] +> ``` + +> [!NOTE] +> - Fix terms references for long-only terms. +> - Fix missing commas in fast start + +> [!NOTE] +> Add missing changelog! + + +## 0.5.0 + +> [!WARNING] +> Starting from Typst v0.12.0 and later, only a single level of indirection +> in the description is supported. This means that the description of an entry +> cannot contain another glossary reference with more than once. See the example +> at +> [`references-in-description`](https://github.com/typst-community/glossarium/blob/master/tests/non-regression/references-in-description.typ) + +> [!NOTE] +> Fix `figure.caption` alignement for glossary entries. + +> [!NOTE] +> Allow terms to have either `short` or `long` or both. + +## 0.4.2 + +> [!TIP] +> For Typst v0.12.0 and later +> A new function is introduced `register-glossary`. +> Recommended usage is the following: +> ```diff +> #import "@preview/glossarium:0.4.0": make-glossary, register-glossary, print-glossary, gls, glspl +> #show: make-glossary +> + #let entry-list = (...) +> + #register-glossary(entry-list) +> ... // Your document body +> #print-glossary( +> - ( +> - ... +> - ) +> + entry-list +> ) +> ``` + +> [!TIP] +> An interface for user customization has been provided through parameters in +> `print-glossary`. See the documentation in +> [`advanced-docs`](https://github.com/typst-community/glossarium/blob/master/advanced-docs/main.pdf) +> for more details. + +> [!NOTE] +> Deprecate `location` argument in queries + +> [!TIP] +> `short` is no longer **required**, but **semi-optional**. +> Accept `short` or `long` for an entry, but not neither. + +## 0.4.1 + +- Resolved an issue causing Glossarium to crash when all entries had a defined, non-empty group. + +## 0.4.0 + +- Support for plurals has been implemented, showcased in [examples/plural-example/main.typ](examples/plural-example). Contributed by [@St0wy](https://github.com/St0wy). +- The behavior of the gls and glspl functions has been altered regarding calls on undefined glossary keys. They now cause panics. Contributed by [@St0wy](https://github.com/St0wy). + +## 0.3.0 + +- Introducing support for grouping terms in the glossary. Use the optional and case-sensitive key `group` to assign terms to specific groups. The appearanceof the glossary can be customized with the new parameter `enable-group-pagebreak`, allowing users to insert page breaks between groups for better organization. Contributed by [indicatelovelace](https://github.com/indicatelovelace). + +## 0.2.6 + +### Added + +- A new boolean parameter `disable-back-references` has been introduced. If set to true, it disable the back-references (the page number at the end of the description of each term). Please note that disabling back-references only disables the display of the page number, if you don't have any references to your glossary terms, they won't show up unless the parameter `show-all` has been set to true. + +## 0.2.5 + +### Fixed + +- Fixed a bug where there was 2 space after a reference. Contributed by [@drupol](https://github.com/drupol) + +## 0.2.4 + +### Fixed + +- Fixed a bug where the reference would a long ref even when "long" was set to false. Contributed by [@dscso](https://github.com/dscso) + +### Changed + +- The glossary appearance have been improved slightlyby. Contributed by [@JuliDi](https://github.com/JuliDi) + +## Previous versions did not have a changelog entry diff --git a/packages/preview/glossarium/0.5.3/LICENSE b/packages/preview/glossarium/0.5.3/LICENSE new file mode 100644 index 000000000..4a27d91be --- /dev/null +++ b/packages/preview/glossarium/0.5.3/LICENSE @@ -0,0 +1,22 @@ +MIT License + +Copyright (c) [2023] [Enib Community] +Copyright (c) [Typst Community] + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. \ No newline at end of file diff --git a/packages/preview/glossarium/0.5.3/README.md b/packages/preview/glossarium/0.5.3/README.md new file mode 100644 index 000000000..bc0e235f6 --- /dev/null +++ b/packages/preview/glossarium/0.5.3/README.md @@ -0,0 +1,248 @@ +# Typst glossary + +> [!TIP] +> Glossarium is based in great part of the work of [Sébastien d'Herbais de Thun](https://github.com/Dherse) from his master thesis available at: . +> His glossary is available under the MIT license [here](https://github.com/Dherse/masterproef/blob/main/elems/acronyms.typ). + +Glossarium is a simple, easily customizable typst glossary inspired by [LaTeX +glossaries package](https://www.ctan.org/pkg/glossaries) . You can see various +examples showcasing the different features in the `examples` folder. + +![Screenshot of a glossary output using glossarium in Typst. A heading with text "Glossary" is displayed, and below four gloss are printed. Each gloss has its short and long form in bold separated by a dash. The description follows after a colon character. A list of the backreferences is given at the end.](.github/example.png) + +# Fast start + +```typ +#import "@preview/glossarium:0.5.3": make-glossary, register-glossary, print-glossary, gls, glspl +#show: make-glossary +#let entry-list = ( + ( + key: "kuleuven", + short: "KU Leuven", + long: "Katholieke Universiteit Leuven", + description: "A university in Belgium.", + ), + // Add more terms +) +#register-glossary(entry-list) +// Your document body +#print-glossary( + entry-list +) +``` + +# I don't like it! + +Take a look at: +- [`acrostiche`](https://typst.app/universe/package/acrostiche) +- [`glossy`](https://typst.app/universe/package/glossy) + +and [many](https://typst.app/universe/search?q=acro) [others](https://typst.app/universe/search?q=glo) + +# Detailed guide + +## Import and setup + +Import the package from the typst preview repository: + +```typ +#import "@preview/glossarium:0.5.3": make-glossary, register-glossary, print-glossary, gls, glspl +``` + +To use **glossarium** as a vendored module, download the package files into your project folder and import `glossarium.typ`: + +```typ +#import "glossarium.typ": make-glossary, register-glossary, print-glossary, gls, glspl +``` + +To use **glossarium** locally, create a new package namespace on your system: +- follows the instructions at [typst/packages](https://github.com/typst/packages?tab=readme-ov-file#local-packages) +- import glossarium (if your namespace is named `local`): + ```typ + #import "@local/glossarium:0.5.3": make-glossary, register-glossary, print-glossary, gls, glspl + ``` + +## Making the glossary + +After importing the package and before making any calls to `gls`, ` print-glossary` or `glspl`, please ***MAKE SURE*** you add this line +```typ +#show: make-glossary +``` + +> [!NOTE] +>

*WHY DO WE NEED THAT?*

+> +> In order to be able to create references to the terms in your glossary using typst [reference syntax](https://typst.app/docs/reference/model/ref/) `@key` glossarium needs to setup some [show rules](https://typst.app/docs/tutorial/advanced-styling/) before any references exist. + +> [!CAUTION] +>

*SHOW RULES CONFLICTS*

+> +> Prefer to use the [selector](https://typst.app/docs/reference/foundations/function/#definitions-where) `figure.where(kind: "image")` or other kinds to avoid conflicts with `glossarium_entry`. +> `make-glossary` can conflict with _global_ figure show rules. Write the user figure show rule before `make-glossary` to avoid any conflicts. +> ![image illustrating a show rule conflict when the user figure show rule is written after make-glossary making the glossary disappear but no effect when it is written before make-glossary.](.github/show_rule_conflict.png) + +## Registering the glossary + +A term is a [dictionary](https://typst.app/docs/reference/types/dictionary/). + +| Key | Type | Required/Optional | Description | +| :------------ | :---------------- | :---------------- | :------------------------------------------------------------------------------------------- | +| `key` | string | required | Case-sensitive, unique identifier used to reference the term. | +| `short` | string | semi-optional | The short form of the term replacing the term citation. | +| `long` | string or content | semi-optional | The long form of the term, displayed in the glossary and on the first citation of the term. | +| `description` | string or content | optional | The description of the term. | +| `plural` | string or content | optional | The pluralized short form of the term. | +| `longplural` | string or content | optional | The pluralized long form of the term. | +| `group` | string | optional | Case-sensitive group the term belongs to. The terms are displayed by groups in the glossary. | + + +```typ +#register-glossary(entry-list) +``` + +```typ +#let entry-list = ( + // Use key as short by default + ( + key: "kuleuven", + ), + // Add SHORT + ( + key: "kuleuven", + short: "KU Leuven" + ), + // Add LONG + ( + key: "unamur", + short: "UNamur", + long: "Namur University", + ), + // Add a DESCRIPTION + ( + key: "oidc", + short: "OIDC", + long: "OpenID Connect", + description: [ + OpenID is an open standard and decentralized authentication protocol promoted by the non-profit + #link("https://en.wikipedia.org/wiki/OpenID#OpenID_Foundation")[OpenID Foundation]. + ], + ), + // Add a PLURAL form + ( + key: "potato", + short: "potato", + // "plural" will be used when "short" should be pluralized + plural: "potatoes", + ), + // Add a LONGPLURAL form + ( + key: "dm", + short: "DM", + long: "diagonal matrix", + // "longplural" will be used when "long" should be pluralized + longplural: "diagonal matrices", + description: "Probably some math stuff idk", + ), + // Add a GROUP + ( + key: "kuleuven", + short: "KU Leuven", + // The terms are displayed by groups in the glossary + group: "Universities", + ), +) +``` + +## Printing the glossary + +Now, you can display the glossary using the `print-glossary` function. + +```typ +#print-glossary(entry-list) +``` + +By default, the terms that are not referenced in the document are not shown in the glossary, you can force their appearance by setting the `show-all` argument to true. + +You can also disable the back-references by setting the parameter `disable-back-references` to `true`. + +By default, group breaks use `linebreaks`. This behaviour can be changed by setting the `user-group-break` parameter to `pagebreak()`, or `colbreak()`, or any other function that returns the `content` you want. + +You can call this function from anywhere in your document. + +## Referencing terms. + +Referencing terms is done using the key of the terms using the `gls` function or the reference syntax. + +```typ +// referencing the OIDC term using gls +#gls("oidc") +// displaying the long form forcibly +#gls("oidc", long: true) + +// referencing the OIDC term using the reference syntax +@oidc +``` + +## Handling plurals + +You can use the `glspl` function and the references supplements to pluralize terms. +The `plural` key will be used when `short` should be pluralized and `longplural` will be used when `long` should be pluralized. If the `plural` key is missing then glossarium will add an 's' at the end of the short form as a fallback. + +```typ +#glspl("potato") +``` + +Please look at the examples regarding plurals. + +## Overriding the text shown + +You can also override the text displayed by setting the `display` argument. + +```typ +#gls("oidc", display: "whatever you want") +``` + +## Styling references links + +I recommend setting a show rule for the links to that your readers understand that they can click on the references to go to the term in the glossary. + +```typ +#show link: set text(fill: blue.darken(60%)) +// links are now blue ! +``` + +It is also possible to apply styling specifically to the glossarium references with a `show ref` rule. Make sure this rule comes **after** `make-glossary`. + +This approach only styles references that use `@ref` and `@ref:pl` instead of `gls("ref")` and `glspl("ref)`. + +```typ +#show: make-glossary + +#show ref: it => { + let el = it.element + if el != none and el.func() == figure and el.kind == "glossarium_entry" { + // Make the glossarium entry references dark blue + text(fill: blue.darken(60%), it) + } else { + // Other references as usual. + it + } +} +``` +(Credits go to flokl for the [solution](https://forum.typst.app/t/how-do-you-apply-a-style-to-glossarium-references-that-is-different-to-other-reference-types/2089/2?u=ogre) on the Typst forums). + +By adding `else if` clauses for different functions and kinds, each type of reference can be given a different style. + +Note that when using the `show ref` rule approach together with a **global** `show link` rule the styling in the `show ref` rule gets overwritten. To avoid this change the `show link` rule to only style specific types, e.g., `str` links (like website or mailto links). + +```typ +#show link: it => { + if type(it.dest) == str { + // Style links to strings red + text(fill: red, it) + } else { + // Return other links as usual + it + } +} +``` \ No newline at end of file diff --git a/packages/preview/glossarium/0.5.3/glossarium.typ b/packages/preview/glossarium/0.5.3/glossarium.typ new file mode 100644 index 000000000..abea810dc --- /dev/null +++ b/packages/preview/glossarium/0.5.3/glossarium.typ @@ -0,0 +1,11 @@ + +// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +// SOFTWARE. + +// @typstyle off +#import "themes/default.typ": gls, agls, glspl, make-glossary, register-glossary, print-glossary, gls-key, gls-short, gls-artshort, gls-plural, gls-long, gls-artlong, gls-longplural, gls-description, gls-group, get-entry-back-references, count-refs, count-all-refs, there-are-refs diff --git a/packages/preview/glossarium/0.5.3/themes/default.typ b/packages/preview/glossarium/0.5.3/themes/default.typ new file mode 100644 index 000000000..0130c0a7a --- /dev/null +++ b/packages/preview/glossarium/0.5.3/themes/default.typ @@ -0,0 +1,1046 @@ + +// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +// SOFTWARE. + +// glossarium figure kind +#let __glossarium_figure = "glossarium_entry" + +// prefix of label for references query +#let __glossary_label_prefix = "__gls:" + +// global state containing the glossary entry and their location +// A glossary entry is a `dictionary`. +// See `__normalize_entry_list`. +#let __glossary_entries = state("__glossary_entries", (:)) + +// glossarium version +#let glossarium_version = "0.5.3" + +// error prefix +#let __glossarium_error_prefix = ( + "glossarium@" + glossarium_version + " error : " +) + +// Errors types +#let __key_not_found = "key_not_found" +#let __attribute_is_empty = "attribute_is_empty" +#let __glossary_is_empty = "glossary_is_empty" +#let __entry_has_neither_short_nor_long = "entry_has_neither_short_nor_long" +#let __make_glossary_not_called = "make_glossary_not_called" +#let __unknown_error = "unknown_error" + +// __error_message(key, kind, ..kwargs) -> str +// Generate an error message +// +// # Arguments +// key (str): the key of the term +// kind (str): the kind of the error +// kwargs (arguments): additional arguments +// +// # Returns +// The error message +#let __error_message(key, kind, ..kwargs) = { + let msg = none + let kwargs = kwargs.named() // convert arguments sink to dictionary + + // Generate the error message + if kind == __key_not_found { + msg = "key '" + key + "' not found" + } else if kind == __attribute_is_empty { + let attr = kwargs.at("attr") + msg = "requested attribute " + attr + "is empty for key '" + key + "'" + } else if kind == __entry_has_neither_short_nor_long { + msg = "entry '" + key + "' has neither short nor long form" + } else if kind == __glossary_is_empty { + msg = "glossary is empty. Use `register-glossary(entry-list)` immediately after `make-glossary`." + } else if kind == __make_glossary_not_called { + msg = "make-glossary not called. Add `#show: make-glossary` at the beginning of the document." + } else { + msg = "unknown error" + } + + // return the error message + return __glossarium_error_prefix + msg +} + +// __query_labels_with_key(loc, key, before: false) -> array