feat(glossy): 0.1.2

preview/glossy/README.md

@@ -43,7 +43,7 @@ different goals:
 ### Import the package
 
 ```typst
-#import "@preview/glossy:0.1.1": *
+#import "@preview/glossy:0.1.2": *
 
 ```
 
@@ -86,6 +86,32 @@ Note that you could also load glossary entries from a data file using
 [#json()](https://typst.app/docs/reference/data-loading/json/), or
 [similar](https://typst.app/docs/reference/data-loading/).
 
+For example, the above glossary could be in this YAML file:
+
+```yaml
+- key: html,
+  short: HTML,
+  long: Hypertext Markup Language,
+  description: A standard language for creating web pages,
+  group: Web
+
+- key: css
+  short: CSS,
+  long: Cascading Style Sheets,
+  description: A stylesheet language used for describing the presentation of a document,
+  group: Web
+
+- key: tps,
+  short: TPS,
+  long: test procedure specification
+```
+
+And then loaded during initialization as follows:
+
+```typst
+#show: init-glossary.with(yaml("glossary.yaml"))
+```
+
 ### Using Glossary Terms in Your Document
 
 Use glossary terms within your text using the `@reference` functionality in
@@ -142,7 +168,27 @@ the title and specify a theme if desired:
 #glossary(title: "Web Development Glossary", theme: my-theme, groups: ("Web"))
 ```
 
-### Themes
+See more on theming below in "Glossary Themes."
+
+### Customizing the Output
+
+#### Term usage in documents
+
+You can control how terms are displayed when using the `@term` reference syntax
+in your document by passing a custom function to `init-glossary` in the
+`show-term` parameter.
+
+For example, if you wanted all terms to be italicized, you could do this:
+
+```typst
+#let emph-term(body) = { emph(body) }
+
+#show: init-glossary.with(myGlossary, show-term: emph-term)
+
+// remainder of document follows
+```
+
+#### Glossary Themes
 
 Customize the appearance of the glossary using themes. Each theme defines how
 sections, groups, and entries are displayed.

preview/glossy/examples/readme.typ

@@ -1,6 +1,92 @@
 // a minimal example, also listed in the README
 
-#import "@preview/glossy:0.1.1": *
+#import "@preview/glossy:0.1.2": *
+
+#let myGlossary = (
+    (key: "html", short: "HTML", long: "Hypertext Markup Language", description: "A standard language for creating web pages", group: "Web"),
+    (key: "css", short: "CSS", long: "Cascading Style Sheets", description: "A language used for describing the presentation of a document", group: "Web"),
+    (key: "tps", short: "TPS", long: "test procedure specification"),
+    // Add more entries as needed
+)
+
+#show: init-glossary.with(myGlossary, show-term: (body) => [#emph(body)])
+
+#set heading(numbering: "1.1")
+
+= Hello, `glossy`!
+
+In modern web development, languages like @html and @css are essential.
+
+Now make sure I get your @tps:short reports by 2pm!
+
+= Examples with modifiers
+
+#table(
+  columns: 2,
+  table.header([*Input*], [*Output*]),
+
+  [`@tps:short`      ], [@tps:short],
+  [`@tps:long`       ], [@tps:long],
+  [`@tps:both`       ], [@tps:both],
+  [`@tps:long:cap`   ], [@tps:long:cap],
+  [`@tps:long:pl`    ], [@tps:long:pl],
+  [`@tps:short:pl`   ], [@tps:short:pl],
+  [`@tps:both:pl:cap`], [@tps:both:pl:cap],
+)
+
+== Using conflicting modifiers (short, long, both)
+
+These modifiers are semantically mutually exclusive, by they can be combined
+syntactically. When multiple are used, `glossy` tries to make a smart choice on
+which one to display.
+
+#table(
+  columns: 2,
+  table.header([*Input*], [*Output*]),
+
+  [`@tps:short:long`     ], [@tps:short:long],
+  [`@tps:short:both`     ], [@tps:short:both],
+  [`@tps:long:both`      ], [@tps:long:both],
+  [`@tps:short:long:both`], [@tps:short:long:both],
+)
+
+#let my-theme = (
+  section: (title, body) => {
+    heading(level: 1, title)
+    body
+  },
+  group: (name, i, n, body) => {
+    if name != "" and n > 1 {
+      heading(level: 2, name)
+    }
+    body
+  },
+  entry: (entry, i, n) => {
+    // i is the entry's index, n is total number of entries
+    let output = [#entry.short]
+    if entry.long != none {
+      output = [#output -- #entry.long]
+    }
+    if entry.description != none {
+      output = [#output: #entry.description]
+    }
+    block(
+      grid(
+        columns: (auto, 1fr, auto),
+        output,
+        repeat([#h(0.25em) . #h(0.25em)]),
+        entry.pages,
+      )
+    )
+  }
+)
+
+#glossary(theme: my-theme)
+#glossary(title: "Glossary with just empty group", groups: ("",), theme: my-theme)
+#glossary(title: "Glossary with just Web group", groups: ("Web",), theme: my-theme)
+// a minimal example, also listed in the README
+
+#import "@preview/glossy:0.1.2": *
 
 #let myGlossary = (
     (key: "html", short: "HTML", long: "Hypertext Markup Language", description: "A standard language for creating web pages", group: "Web"),
@@ -44,12 +130,10 @@ which one to display.
   columns: 2,
   table.header([*Input*], [*Output*]),
 
-[`@tps:short:long`      ], [@tps:short:long],
+  [`@tps:short:long`      ], [@tps:short:long],
-[`@tps:long:short`      ], [@tps:long:short],
+  [`@tps:short:both`       ], [@tps:short:both],
-[`@tps:short:both`       ], [@tps:short:both],
+  [`@tps:long:both`       ], [@tps:long:both],
-[`@tps:long:both`       ], [@tps:long:both],
+  [`@tps:short:long:both`   ], [@tps:short:long:both],
-[`@tps:short:long:both`   ], [@tps:short:long:both],
-[`@tps:long:pl`    ], [@tps:long:pl],
 )
 
 #let my-theme = (

preview/glossy/src/gloss.typ

@@ -215,7 +215,9 @@
 // Main wrapper (usually used in a `#show: init-glossary`) which loads the
 // entries passed in into our state. Furthermore, hooks into references so that
 // we can intercept term usage in a doc and label them appropriately.
-#let init-glossary(entries, body) = context {
+//
+// Pass a function in `show-term(term-body)` to control how you display terms.
+#let init-glossary(entries, show-term: (term-body) => term-body, body) = context {
   for entry in __normalize_entries(entries) {
     __add_entry(entry)
   }
@@ -224,7 +226,7 @@
   show ref: r => {
     let (key, ..modifiers) = str(r.target).split(":")
     if __has_entry(key) {
-      __gls(key, modifiers: modifiers)
+      show-term(__gls(key, modifiers: modifiers))
     } else {
       r
     }