diff --git a/glossy/README.md b/glossy/README.md index 65dadd7..c51dd58 100644 --- a/glossy/README.md +++ b/glossy/README.md @@ -41,7 +41,7 @@ different goals: ### Import the package ```typst -#import "@preview/glossy:0.5.2": * +#import "@preview/glossy:0.6.0": * ``` ### Defining Glossary Terms @@ -143,6 +143,7 @@ Available modifiers: - **short**: Shows only short form - **long**: Shows only long form - **def** or **desc**: Shows the description +- **noref** or **noindex**: Don't show the term in the glossary. - **a** or **an**: Include the article (`an` is just an alias of `a`, they're equivalent) @@ -160,6 +161,9 @@ Modifiers can be combined with colons: | `@tps:short:pl` | "TPSes" | | `@tps:both:pl:cap` | "Technical procedure specifications (TPSes)" | | `@tps:def` | "A formal document describing test steps and expected results" | +| `@tps:desc` | _same as above, `desc` is an alias for `def`_ | +| `@tps:noref` | _works as normal, just won't show up in glossary_ | +| `@tps:noindex` | _same as above, `noindex` is an alias for `noref`_ | The `a`/`an` modifier is special because it can either precede or follow the term's key. @@ -180,6 +184,18 @@ For example: Note that the `a`/`an` (article) modifier cannot be combined with the `pl` (plural) modifier. +### First use logic + +Any use of the `short`, `long`, or `both` modifier will not count against the +term's first use. + +This is useful, for example, when you want to use a term in a heading or a +caption. In that case, your term might end up in an `outline()` at the top of +your document. Normally you don't want that to count as a term's first real use. +Normally you want that to happen in the body of your document. So, by using +these modifiers in such situations, you can not only specify exactly how you +want your term to appear, but also control whether it counts as a "first use". + ### Generating the Glossary Display the glossary using the `glossary()` function: diff --git a/glossy/src/gloss.typ b/glossy/src/gloss.typ index d5d9e99..dce47c2 100644 --- a/glossy/src/gloss.typ +++ b/glossy/src/gloss.typ @@ -7,6 +7,7 @@ #let __gloss_entries = state("__gloss_entries", (:)) #let __gloss_label_prefix = "__gloss:" +#let __gloss_first_use_counter_postfix = ":first-use-count" // Normalizes a dictionary entry by ensuring all required and optional keys exist // with appropriate default values. @@ -129,11 +130,14 @@ // Returns: // none: Updates state as a side effect // -#let __mark_term_used(key) = { +#let __mark_term_used(key, count-as-first-use) = { counter(__gloss_label_prefix + key).step() + if count-as-first-use { + counter(__gloss_label_prefix + key + __gloss_first_use_counter_postfix).step() + } } -// Queries the term usage +// Queries whether the term is used ANYWHERE // // Parameters: // key (string): The glossary entry key @@ -142,12 +146,29 @@ // Returns: // boolean: If the entry is used above the location in the document // -#let __is_term_used(key, location: none) = { +#let __is_term_ever_used(key, location: none) = { let c = counter(__gloss_label_prefix + key) c = if location == none {c.final()} else {c.at(location)} c.at(0) > 0 } +// Queries whether the term has been "first used" +// +// "First used" is used to determine how to display the term, either "long +// (short)" or just "(short)" +// +// Parameters: +// key (string): The glossary entry key +// location (location): The location in the document. Use none for end of document +// +// Returns: +// boolean: If the entry is used above the location in the document +// +#let __is_term_first_used(key, location: none) = { + let c = counter(__gloss_label_prefix + key + __gloss_first_use_counter_postfix) + c = if location == none {c.final()} else {c.at(location)} + c.at(0) > 0 +} // Determine if the glossary contains a visible entry // @@ -216,8 +237,12 @@ // --------------------------------------------------------------------------- // Manage term usage counting and determine if it's the first reference // --------------------------------------------------------------------------- - let is_first_use = not __is_term_used(key, location: here()) - __mark_term_used(key) + let is_first_use = not __is_term_first_used(key, location: here()) + let count-as-first-use = ("short" not in modifiers and "long" not in modifiers and "both" not in modifiers) + let wants_reference = ("noref" not in modifiers and "noindex" not in modifiers) + if wants_reference { + __mark_term_used(key, count-as-first-use) + } // --------------------------------------------------------------------------- // Helper Functions @@ -342,15 +367,20 @@ } else { term } - [#article#show-term(linked-term)#metadata(term)#__term_label(key)] - // |^^^^^^^|^^^^^^^^^ |^^^^^^^^ |^^^^^^^^^^^^ - // \_art. | | | + let term-label = if wants_reference { + __term_label(key) + } else { + [] + } + [#article#show-term(linked-term)#metadata(term)#term-label] + // |^^^^^^^|^^^^^^^^^ |^^^^^^^^ |^^^^^^^^^^^^ + // \_art. | | | // \_ apply user formatting function to the term - // | | - // \_ metadata lets us label (ie it's "labelable") - // | - // \_ i.e. <__gloss:key>, etc. - // for backlink from glossary + // | | + // \_ metadata lets us label (ie makes it "labelable") + // | + // \_ i.e. <__gloss:key>, etc. + // for backlink from glossary } } @@ -554,7 +584,7 @@ // Collect and organize entries by group let output = (:) let all_entries = __gloss_entries.final() - let all_used = all_entries.keys().filter(key => __is_term_used(key)) + let all_used = all_entries.keys().filter(key => __is_term_ever_used(key)) // Determine which groups to process let all_groups = all_entries diff --git a/glossy/src/themes/academic.typ b/glossy/src/themes/academic.typ index 5283ea3..975c8ad 100644 --- a/glossy/src/themes/academic.typ +++ b/glossy/src/themes/academic.typ @@ -1,7 +1,6 @@ // Inspired by academic textbook glossaries #let theme-academic = ( section: (title, body) => { - set text(font: "New Computer Modern") heading(level: 1, title) v(1em) body diff --git a/glossy/tests/abbreviated-syntax/ref/1.png b/glossy/tests/abbreviated-syntax/ref/1.png index d99fd9e..0def5d0 100644 Binary files a/glossy/tests/abbreviated-syntax/ref/1.png and b/glossy/tests/abbreviated-syntax/ref/1.png differ diff --git a/glossy/tests/demo/ref/1.png b/glossy/tests/demo/ref/1.png index fe0c567..9a91e44 100644 Binary files a/glossy/tests/demo/ref/1.png and b/glossy/tests/demo/ref/1.png differ diff --git a/glossy/tests/demo/test.typ b/glossy/tests/demo/test.typ index ff28dcb..0a422bb 100644 --- a/glossy/tests/demo/test.typ +++ b/glossy/tests/demo/test.typ @@ -47,6 +47,8 @@ Now make sure I get @tps:a:SHORT report by 2pm! @an:tps:cap is very important!!! [`@tps:both:pl:cap`], [@tps:both:pl:cap], [`@tps:def` ], [@tps:def], [`@tps:desc` ], [@tps:desc], + [`@tps:noref` ], [@tps:noref *(not listed in glossary)*], + [`@tps:noindex` ], [@tps:noindex *(not listed in glossary)*], ) == Adding articles via `a`/`an` modifiers diff --git a/glossy/tests/format-term/ref/1.png b/glossy/tests/format-term/ref/1.png index 24a7d77..bf265a6 100644 Binary files a/glossy/tests/format-term/ref/1.png and b/glossy/tests/format-term/ref/1.png differ diff --git a/glossy/tests/forward-links/ref/1.png b/glossy/tests/forward-links/ref/1.png index b07f5d8..76a3c85 100644 Binary files a/glossy/tests/forward-links/ref/1.png and b/glossy/tests/forward-links/ref/1.png differ diff --git a/glossy/tests/group-specified/ref/1.png b/glossy/tests/group-specified/ref/1.png index 48e2d52..e4c27de 100644 Binary files a/glossy/tests/group-specified/ref/1.png and b/glossy/tests/group-specified/ref/1.png differ diff --git a/glossy/tests/group-specified/ref/2.png b/glossy/tests/group-specified/ref/2.png index 2de3f10..3f1d8b2 100644 Binary files a/glossy/tests/group-specified/ref/2.png and b/glossy/tests/group-specified/ref/2.png differ diff --git a/glossy/tests/group-specified/ref/3.png b/glossy/tests/group-specified/ref/3.png index 0b84231..74a0947 100644 Binary files a/glossy/tests/group-specified/ref/3.png and b/glossy/tests/group-specified/ref/3.png differ diff --git a/glossy/tests/group-specified/ref/4.png b/glossy/tests/group-specified/ref/4.png index e195891..67a9c3d 100644 Binary files a/glossy/tests/group-specified/ref/4.png and b/glossy/tests/group-specified/ref/4.png differ diff --git a/glossy/tests/no-sort/ref/1.png b/glossy/tests/no-sort/ref/1.png index de6c93b..698cb7d 100644 Binary files a/glossy/tests/no-sort/ref/1.png and b/glossy/tests/no-sort/ref/1.png differ diff --git a/glossy/tests/noref/ref/1.png b/glossy/tests/noref/ref/1.png new file mode 100644 index 0000000..4aad2c9 Binary files /dev/null and b/glossy/tests/noref/ref/1.png differ diff --git a/glossy/tests/noref/test.typ b/glossy/tests/noref/test.typ new file mode 100644 index 0000000..ba62835 --- /dev/null +++ b/glossy/tests/noref/test.typ @@ -0,0 +1,26 @@ +#import "/lib.typ": * + +// Our test glossary +#show: init-glossary.with(( + Normal: "this is a normal term", + NoRef: "this term is noref'd", + NoIndex: "this term is noindex'd", + NoRefNoIndex: "this term is noref'd and noindex'd", +)) + +// Configure styling + +#set page(margin: 1em) +#set page(width: 3.5in) +#set page(height: auto) +#set text(size: 10pt) + +@Normal + +@NoRef:noref + +@NoIndex:noindex + +@NoRefNoIndex:noref:noindex + +#glossary() diff --git a/glossy/tests/refs-in-captions/ref/1.png b/glossy/tests/refs-in-captions/ref/1.png new file mode 100644 index 0000000..34d3905 Binary files /dev/null and b/glossy/tests/refs-in-captions/ref/1.png differ diff --git a/glossy/tests/refs-in-captions/test.typ b/glossy/tests/refs-in-captions/test.typ new file mode 100644 index 0000000..7f2cc5e --- /dev/null +++ b/glossy/tests/refs-in-captions/test.typ @@ -0,0 +1,82 @@ +#import "/lib.typ": * + +// Our test glossary +#show: init-glossary.with(( + ShortInHeader: "short used in header", + ShortInCaption: "short used in caption", + LongInHeader: "long used in header", + LongInCaption: "long used in caption", + BothInHeader: "both used in header", + BothInCaption: "both used in caption", + NormalInHeader: "unmodified use in header", + NormalInCaption: "unmodified use in caption", +)) + +// Configure styling + +#set page(numbering: "1") +#set page(margin: 0.5in) +#set page(height: auto) +#set text(size: 10pt) + +// Outlines + +#outline(title:"Table of Contents", indent: auto) +#outline(title: "List of Figures", target: figure.where(kind: image)) +#block( + height:7em, + glossary(title: "List of Abbreviations", theme: theme-twocol) +) + +#line(length: 100%) + +// Doc Body + +// Use all the terms in headings +#heading(level: 1, outlined: false, [Use terms in HEADERS]) + +=== `@ShortInHeader:short` = "@ShortInHeader:short" +=== `@LongInHeader:long` = "@LongInHeader:long" +=== `@BothInHeader:both` = "@BothInHeader:both" +=== `@NormalInHeader` = "@NormalInHeader" + +#line(length: 100%) + +// Use all the terms in captions +#heading(level: 1, outlined: false, [Use terms in CAPTIONS]) + +#figure([], caption: [`@ShortInCaption:short` = "@ShortInCaption:short"]) +#figure([], caption: [`@LongInCaption:long` = "@LongInCaption:long"]) +#figure([], caption: [`@BothInCaption:both` = "@BothInCaption:both"]) +#figure([], caption: [`@NormalInCaption` = "@NormalInCaption"]) + +#line(length: 100%) + +// Now use the terms in the body to see if they handle "first use" correctly +#heading(level: 1, outlined: false, [Use terms in BODY]) + +First `@ShortInHeader` = "@ShortInHeader". +Second `@ShortInHeader` = "@ShortInHeader" + +First `@LongInHeader` = "@LongInHeader". +Second `@LongInHeader` = "@LongInHeader". + +First `@BothInHeader` = "@BothInHeader". +Second `@BothInHeader` = "@BothInHeader". + +First `@NormalInHeader` = "@NormalInHeader". +Second `@NormalInHeader` = "@NormalInHeader". + +#v(0.5em) + +First `@ShortInCaption` = "@ShortInCaption". +Second `@ShortInCaption` = "@ShortInCaption" + +First `@LongInCaption` = "@LongInCaption". +Second `@LongInCaption` = "@LongInCaption". + +First `@BothInCaption` = "@BothInCaption". +Second `@BothInCaption` = "@BothInCaption". + +First `@NormalInCaption` = "@NormalInCaption". +Second `@NormalInCaption` = "@NormalInCaption". diff --git a/glossy/tests/theme-gallery/ref/1.png b/glossy/tests/theme-gallery/ref/1.png index f37d043..f4c666a 100644 Binary files a/glossy/tests/theme-gallery/ref/1.png and b/glossy/tests/theme-gallery/ref/1.png differ diff --git a/glossy/themeshots.png b/glossy/themeshots.png index 9274762..49b0f8b 100644 Binary files a/glossy/themeshots.png and b/glossy/themeshots.png differ diff --git a/glossy/thumbnail.png b/glossy/thumbnail.png index 3c7f7e0..5f43827 100644 Binary files a/glossy/thumbnail.png and b/glossy/thumbnail.png differ diff --git a/glossy/typst.toml b/glossy/typst.toml index c10f290..f1da265 100644 --- a/glossy/typst.toml +++ b/glossy/typst.toml @@ -1,6 +1,6 @@ [package] name = "glossy" -version = "0.5.2" +version = "0.6.0" entrypoint = "lib.typ" authors = ["Stephen Waits "] license = "MIT"