Rename long to first, and always-long to always-first

Author: quachpas

CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.5.10
+
+> [!NOTE]
+> The changelog incorrectly states that `@gls:long` and `#gls("gls", long: true)` are the same.
+> The option `long` of `gls` and others similar functions has been renamed to `first`
+> to better reflect the real meaning of the option. (reported in #172 by @haenoe)
+> `make-glossary`'s option has been renamed from `always-long` to `always-first`.
+>
+> In fact, the long in `@gls:long` refers to the long attribute in the entry's
+> definition, whereas the long in `#gls(...)` refers to the "long form" of the
+> entry's output.
+
+
 ## 0.5.9
 
 > [!TIP]

README.md

@@ -87,16 +87,16 @@ After importing the package and before making any calls to `gls`, ` print-glossa
 
 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 or content | 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.                            |
-| `custom`      | any               | optional          | Custom content for usage in "user functions", e.g. `user-print-glossary` (see [advanced docs](./advanced-docs/main.pdf))|
+| Key           | Type              | Required/Optional | Description                                                                                                              |
+| :------------ | :---------------- | :---------------- | :----------------------------------------------------------------------------------------------------------------------- |
+| `key`         | string            | required          | Case-sensitive, unique identifier used to reference the term.                                                            |
+| `short`       | string or content | 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.                             |
+| `custom`      | any               | optional          | Custom content for usage in "user functions", e.g. `user-print-glossary` (see [advanced docs](./advanced-docs/main.pdf)) |
 
 
 ```typ
@@ -187,15 +187,15 @@ Referencing terms can be done in different ways. The function with the largest f
 ```typ
 // Referencing the OIDC term using gls
 #gls("oidc")
-// Displaying the long form forcibly
-#gls("oidc", long: true)
+// Displaying the first form forcibly
+#gls("oidc", first: true)
 // Do not add a link
 #gls("oidc", link: false)
 // Do not update the usage count. If done on first use, the next reference will trigger printing the full version.
 #gls("oidc", update: false)
 ```
 
-The graph below is an overview of the available interface groups and their individual functions/modifiers. 
+The graph below is an overview of the available interface groups and their individual functions/modifiers.
 
 ```mermaid
 graph TD;
@@ -209,12 +209,12 @@ graph TD;
     gls --> at-syntax;
 ```
 
-Usually, you will want to use Typst reference syntax (`@` syntax). This is the most practical way to reference an entry. By default, some shorthands are made available: plural, capitalize, capitalized plural, short and long. 
+Usually, you will want to use Typst reference syntax (`@` syntax). This is the most practical way to reference an entry. By default, some shorthands are made available: plural, capitalize, capitalized plural, short and long.
 
 ```typ
 // Prints the full version on first usage, short afterwards
 @oidc
-// Will always display the long version 
+// Will always display the long version
 @oidc:long
 // Display the plural form
 @oidc:pl
@@ -233,11 +233,11 @@ print-glossary(
 
 The different interfaces have different default parameters which you should keep in mind when using them. In most cases, you will not need to manually set `update: false`, unless you are using `gls` in situations that create ambiguity, e.g., using `gls` in other entries' description.
 
-| Interface                                     | `update` | `link`  |
-| --------------------------------------------- | :------: | :-----: |
-| `gls`, `Gls`, `glspl`, etc.                   | `true`   | `true`  |
-| Access values<br>(`gls-short`, ...)           | `false`  | `false` |
-| Reference syntax<br>(`@oidc:pl`, ...)         | `true`   | `true`  |
+| Interface                             | `update` | `link`  |
+| ------------------------------------- | :------: | :-----: |
+| `gls`, `Gls`, `glspl`, etc.           |  `true`  | `true`  |
+| Access values<br>(`gls-short`, ...)   | `false`  | `false` |
+| Reference syntax<br>(`@oidc:pl`, ...) |  `true`  | `true`  |
 
 ### Handling plurals
 
@@ -333,7 +333,7 @@ Note that when using the `show ref` rule approach together with a **global** `sh
 Further customization is possible. Here is a short list of alternative functions you can pass to `print-glossary` to modify the layout.
 
 - `user-print-glossary`: print the entire glossary
-- `user-print-group-heading`: print the group heading 
+- `user-print-group-heading`: print the group heading
 - `user-group-break`: display a break between groups
 - `user-print-gloss`: print one entry
 - `user-print-title`: print the entry's title

examples/full-example/main.typ

@@ -9,7 +9,8 @@
     short: "KU Leuven",
     long: "Katholieke Universiteit Leuven",
     longplural: "Katholieke Universiteiten Leuven",
-    description: [Fugiat do fugiat est minim ullamco est eu duis minim nisi tempor adipisicing do _sunt_. #gls("vub")],
+    description: [Fugiat do fugiat est minim ullamco est eu duis minim nisi
+      tempor adipisicing do _sunt_. #gls("vub")],
     plural: "KU Leuvens",
     artshort: "the",
     artlong: "the",
@@ -30,9 +31,9 @@
     key: "vub",
     short: "VUB",
     long: "Vrije Universiteit Brussel",
-    description: [Proident veniam non aliquip commodo sunt cupidatat. Enim est cupidatat occaecat
-      elit et. Adipisicing irure id consequat ullamco non. Labore sunt tempor et
-      mollit. #gls("kuleuven", long: true)],
+    description: [Proident veniam non aliquip commodo sunt cupidatat. Enim est
+      cupidatat occaecat elit et. Adipisicing irure id consequat ullamco non.
+      Labore sunt tempor et mollit. #gls("kuleuven", first: true)],
   ),
   (
     key: "ulb",
@@ -67,8 +68,8 @@
   (
     key: "notused",
     short: "Not used",
-    description: [This key is not cited anywhere, it won't be in the glossary unless the
-      `show-all` argument is set to true],
+    description: [This key is not cited anywhere, it won't be in the glossary
+      unless the `show-all` argument is set to true],
   ),
 )
 #register-glossary(entry-list)
@@ -80,18 +81,25 @@
 
 There are many Belgian universities, like @kuleuven and @ulb. When repeating
 their names, they won't show as a long version: @kuleuven, @ulb. But we can
-still force them to be long using the `gls` function: #gls("kuleuven", long: true).
+still force them to be long using the `gls` function: #gls(
+  "kuleuven",
+  first: true,
+).
 
-We can also force them to be short: #gls("kuleuven", long: false). Finally, we
+We can also force them to be short: #gls("kuleuven", first: false). Finally, we
 can make them plural:
 + using the `suffix` parameter: #gls("kuleuven", suffix: "s"), or
 + using the additional `supplement` onto the `ref`: @kuleuven[s], or
 + the plural function `#glspl(key: "kuleuven")` #glspl("kuleuven"), or
 + call `@kuleuven:pl` @kuleuven:pl
 
-It is also possible to use the proper article with `#agls("lod")`: "#agls("lod") system", "#agls("lod") system".
+It is also possible to use the proper article with `#agls("lod")`: "#agls("lod")
+system", "#agls("lod") system".
 
-You can also override the text shown by setting the `display` argument: #gls("kuleuven", display: "whatever you want")
+You can also override the text shown by setting the `display` argument: #gls(
+  "kuleuven",
+  display: "whatever you want",
+)
 
 Attributes of an entry can be retrieved using the available functions:
 - `gls-key("kuleuven")`: #gls-key("kuleuven")

tests/always-long/.gitignore tests/always-first/.gitignoretests/always-long/.gitignore renamed to tests/always-first/.gitignore

@@ -1,8 +1,8 @@
 #import "../../themes/default.typ": *
 
-== always-long
+== always-first
 
-#show: make-glossary.with(always-long: true)
+#show: make-glossary.with(always-first: true)
 #let entry-list-8 = (
   (
     key: "short",

tests/always-first/ref/1.png

@@ -33,7 +33,8 @@
     key: "hidden potato",
     short: "hiddenpotato",
     group: "show-all test",
-    description: [This potato does not appear, unless `print-glossary` is called with `show-all: true`],
+    description: [This potato does not appear, unless `print-glossary` is called
+      with `show-all: true`],
   ),
 )
 #let entry-list-2 = (
@@ -156,11 +157,11 @@ First: #gls("potato")
 
 Display: #gls("potato", display: "potato text")
 
-Force long: #gls("potato", long: true)
+Force long: #gls("potato", first: true)
 
 1st ref. when long is empty defaults to short: #gls("potato A")
 
-Force long when empty defaults to short: #gls("potato A", long: true)
+Force long when empty defaults to short: #gls("potato A", first: true)
 
 2nd ref.: #gls("potato A")
 
@@ -170,9 +171,9 @@ Force long when empty defaults to short: #gls("potato A", long: true)
 
 First: #glspl("potato C")
 
-Force long: #glspl("potato", long: true)
+Force long: #glspl("potato", first: true)
 
-Force long when empty defaults to plural: #glspl("potato A", long: true)
+Force long when empty defaults to plural: #glspl("potato A", first: true)
 
 2nd ref.: #glspl("potato A")
 
@@ -229,8 +230,7 @@ Only list 4: #context count-all-refs(entry-list: entry-list-4)
 == #there-are-refs
 
 true: #context there-are-refs()
-)
-false: #context there-are-refs(groups: (" ",))
+) false: #context there-are-refs(groups: (" ",))
 
 #context if there-are-refs(entry-list: ((key: "potato A"),)) [
   There are refs to potato A in the document.