The selection of which mode was shown was pretty complex. This is now
simplified.
First, when the mode is `auto`, the requested mode is adapted depending
on the first use counter.
Then, it is determined if the requested mode can be fulfilled or if a
fallback mode should be selected.
After this simple process, the mode is determined.
Based on #47 from BurningKarl
When an unrecognized modifier is applied, glossy should panic to warn
the user, instead of silently ignoring the modifier. This might catch
potential misspellings of modifiers.
When multiple modes are requested at the same time
(like 'long' & 'short'), panic with a clear error message.
This is better than guessing what the user wanted.
The list of modes & modifiers is now normalized (i.e. multiple equal
names are mapped to the same internal name, e.g. 'def' and 'desc' are
mapped to 'description').
Some sanitization is applied (not yet rigorously).
The internals are now splitted in a list of modes and a list of
modifiers.
These two actions already simplify a lot of logic (no multiple checks
for 'def' and 'desc' for example).
A breaking change, by default the `both` mode now counts towards the
first use of a term. This in accordance to the documentation.
(updated in bffe5fdc35fcb67aca188fc0642db5bf23530bcd!)
Added the `:use`/`:spend` and `:nouse`/`:nospend` modifiers, in
accordance with the documentation.
(updated in bffe5fdc35fcb67aca188fc0642db5bf23530bcd!)
The 'wants to be referenced from the index/glossary' counter is now
decoupled from the '(first) usage' counter. This is made consistent with
the documentation (updated in bffe5fdc35fcb67aca188fc0642db5bf23530bcd!).
Furthermore, when the 'supplement' mode is used, the term is now NOT
counted as (first) used (by default). This is now consistent with the
documentation.
Add a mode, two modifiers and change the default usage behaviour of some
modes. This documents the glossy 'API' when using terms with respect to
the usage counter.
Important!
At the moment, this is a description of the intended endresult
(documentation driven development). Next commits will bring the code in
accordance with this desired result.
This distinction between 'mode' vs 'modifier' is already a bit visible
when looking at which modifiers can be combined and what output they
produce. This is just formalizing and categorizing that behaviour.
Also create a comprehensive reference table for all modes and modifiers.
This distinction is made in preparation for more modes & modifiers to
control the usage counter, while keeping everything understandable.
Instead of returning an opaque context element with a fixed list of the
pages, return an array of context elements with each a page
(already unique!).
This is conceptually cleaner. Now it's the themes responsability to join
the array of unique pages however it wants. Most times, this will be a
`.join(", ")`, but could be e.g. `.first()` if the theme only wants to
show the page of the first occurance of this term.
Also update the documentation.
Breaking API change in the themes.
No visual differences (tests remain the same), but there are binary
differences.
This modifier was not orthogonal with other modifiers (for example, it
could not be used together with :noindex)
Added documentation and modified test to reflect that @term[] with an
empty supplement has exactly the same result *and* is more orthogonal.
This partially reverts commit 5957432d5d.
Ensure an empty supplement results in glossy returning empty content,
instead of an empty string. Done by returning #none if no article is
wanted.
When the value #none is returned for the article, this can neatly join
with the other values without a trace. In particular, when `term` is
empty content, this ensures that only #metadata remains, exactly like
in the 'hidden' case.
Effectively, now @term[] is identical to @term:hidden, because no empty
string is inserted. This can be seen in the updated test case, where the
spaces around the blank term are now collapsed to a single space by
Typst, instead of keeping two spaces like before.
A next commit will remove :hidden, since it's not orthogonal w.r.t.
other modifiers, while using a supplement is.
If you want to completely override how a term is displayed, you can pass
content in via the square brackets on the term's reference.
For example, a term @www which might normally display as "worldwide web
(WWW)" or something similar, could instead display as FOOBAR by using
@www[FOOBAR].
There are cases where you might want a term referenced (ie from the
Glossary/Index), but don't want to display it. New modifiers
`hide`||`hidden` do exactly that.
This parameter (to init-glossary()) enables/disables the terms in the
document linking to their place in the glossary. However, this adds a
crazy amount of extra queries which sometimes hinders Typst's ability to
converge on documents.
Closes [#24](https://github.com/swaits/typst-collection/issues/24)
- Fixed academic theme (no longer hardcodes a font)
- New modifiers: noref/noindex - keeps terms out of glossary
- New behavior: short/long/both no longer count against "first use"
New feature:
`init-glossary()` now accepts a `format-term()` function which gives the
user control over how the short-form and long-form of the terms are
assembled based on the needed mode ("short", "long", or "both").
Change:
Default theme changed to `theme-academic`, which is probably more
generally useful than the prior (`theme-twocol`).
Idea [from Discord
conversation](https://discord.com/channels/1054443721975922748/1318670789150642246/1319338465757757562).
Let's users more precisely control how short-form and long-form terms
are used based on the mode ("short", "long", or "both").
Defaults to `__default-format-term()` as below:
```typst
// Formats a term string based on the specified mode.
//
// Given mode, long-form, and short-form, this function returns the formatted
// term based on the mode. When mode is ...
//
// - "short" -> returns "short-form"
// - "long" -> returns "long-form"
// - "both" -> returns "short-form (long-form)"
//
// Parameters:
// mode (string): The mode in which to format the term. Possible values are "short", "long", or "both".
// short-form (string): The short form of the term.
// long-form (string): The long form of the term.
//
// Returns:
// string: The formatted term based on the specified mode.
//
#let __default-format-term(mode, short-form, long-form) = {
if mode == "short" {
short-form
} else if mode == "long" {
long-form
} else {
// mode assumed to be "both"
long-form + " (" + short-form + ")"
}
}
```
- Merges [16](https://github.com/swaits/typst-collection/pull/16).
- Fixes [3](https://github.com/swaits/typst-collection/issues/3).
A big PR from [@eltos](https://github.com/eltos)!
This adds labels for each `key`, so that auto-complete (in the typst.app
/ `typst-ide`) works properly. It also makes it so terms can link to
their glossary entry. In the case that terms are used but no glossary is
shown (which is a core feature of Glossy), placeholder labels are used
so that the auto-complete still works.
All tests, but one (theme-gallery), passed straight from the PR. The
ddiff in the `theme-gallery` test were non-visible (ie a few pixels),
making it effectively passing too. Updated that test so it passes, and
updated the theme screenshot to match its output as well.
Huge thanks to [@eltos](https://github.com/eltos) who demonstrates a
deep understanding of Typst!
## New features:
**Articles with `a`/`an` modifier**
Now you can include articles using this new modifier. The articles may
be defined in your dictionary entry (fields `artcile`, and
`longarticle`). But, if you don't define them, Glossy will do a
reasonably good job at guessing them.
This modifier is also allowed before the term. For example, you might
have this term:
```yaml
www: Worldwide Web
```
And you could display it with an article by any of these:
```typst
@a:www
@an:www
@www:a
@www:an
```
These, `a` and `an` are exactly equivalent. They're just provided for
your convenience. Use either or both.
The `a`/`an` modifier works with all modifiers except `pl` and
`def`/`desc`.
If you want to define custom articles for your terms, do so like this:
```typst
#let glossary = (
rf: (
short: "RF",
article: "an",
long: "radio frequency",
longarticle: "a",
)
uts: (
short: "UTS",
article: "a",
long: "untranslatable string",
longarticle: "an",
)
)
```
But again, in most cases (for English) you shouldn't need to because
Glossy should usually get it right.
Fixes [#12](https://github.com/swaits/typst-collection/issues/12).
## Other changes:
- added test which exhausts all reference options
- added panic if 'def'/'desc' used when no `description` field exists
- significantly improved the (English) pluralizer function
- `__gls()` function refactored, cleaned up
- removed a rogue PDF
## Contributors:
- [@eltos](https://github.com/eltos)
- [@theRealProHacker](https://github.com/theRealProHacker)
swaits