swaits/typst-collection
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

test(glossy): add test to exhaust all reference options

Browse Source
This commit is contained in:
swaits committed 2024-12-18 10:14:18 -07:00
2 parents ba8fdda1bf 3dce3d1734
commit a8e0ef7c02
9 files changed
+1054 -70
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

glossy/src/gloss.typ
+197 -68
View File
@@ -53,8 +53,10 @@
(
short: entry.short,
plural: entry.at("plural", default: __pluralize(entry.short)),
article: entry.at("article", default: __determine_article(entry.short)),
long: long,
longplural: entry.at("longplural", default: __pluralize(long)),
longarticle: entry.at("longarticle", default: __determine_article(long)),
description: entry.at("description", default: none),
group: entry.at("group", default: "")
)
@@ -176,95 +178,203 @@
// Renders a glossary term with various formatting options.
//
// This function handles the display of terms in the document, managing both first
// and subsequent uses, pluralization, capitalization, and different display forms
// (short, long, or combined forms).
//
// Parameters:
// key (string): The glossary entry key to render
// key (string): The glossary entry key to render.
// modifiers (array): Array of modifier strings that control term rendering:
// - "cap": Capitalize the first letter of the term
// - "pl": Use plural form of the term
// - "both": Show "Long form (short form)"
// - "short": Show only the short form
// - "long": Show only the long form
// - "def" or "desc": Show the term's description instead
//
// Returns:
// content: Formatted term with appropriate labels and metadata
// - "cap": Capitalize the first letter of the term.
// - "pl": Use plural form of the term.
// - "both": Show "Long form (short form)".
// - "short": Show only the short form.
// - "long": Show only the long form.
// - "def" or "desc": Show the term's description instead of its name.
// - "a" or "an": Prepend an article, chosen from the entry (short or long form).
// show-term (function): A function that renders the chosen term.
//
// Behavior:
// - Without modifiers, first use shows "Long form (short form)", subsequent uses show short form
// - Explicit modifiers override the default first-use behavior
// - If long form is requested but unavailable, falls back to short form
// - Maintains usage counter for term references
// - Without modifiers, the first use of a term shows "Long form (short form)",
// subsequent uses show only the short form.
// - Explicit modifiers ("long", "short", "both") override the default behavior.
// - If a requested long form doesn't exist, the logic falls back to the short form.
// - A usage counter tracks how many times a term has been referenced.
//
#let __gls(key, modifiers: array) = {
// Fetch the entry and prepare label
// Returns:
// content: The fully formatted term, including optional article, capitalization,
// usage tracking metadata, and the chosen form (short, long, or both).
//
#let __gls(key, modifiers: array, show-term: function) = {
// ---------------------------------------------------------------------------
// Check for illegal modifier combinations
// ---------------------------------------------------------------------------
if ("def" in modifiers or "desc" in modifiers) and modifiers.len() > 1 {
panic("Cannot use 'def'/'desc' with other modifiers.")
}
if ("a" in modifiers or "an" in modifiers) and ("pl" in modifiers) {
panic("Cannot use 'a'/'an' and 'pl' together.")
}
// ---------------------------------------------------------------------------
// Retrieve the glossary entry and its label
// ---------------------------------------------------------------------------
let entry = __get_entry(key)
let entry_label = __dict_label_str(key)
// Handle description mode
// ---------------------------------------------------------------------------
// If "def" or "desc" modifier is present, show the entry's description immediately
// ---------------------------------------------------------------------------
if "def" in modifiers or "desc" in modifiers {
return [#entry.description]
if entry.description == none {
panic("Use of 'def'/'desc' requires a description be defined.")
}
return show-term([#entry.description])
}
// Track term usage
// ---------------------------------------------------------------------------
// Manage term usage counting and determine if it's the first reference
// ---------------------------------------------------------------------------
let entry_counter = counter(entry_label)
entry_counter.step()
let key_index = entry_counter.get().first()
let first = key_index == 0
let is_first_use = key_index == 0
// ---------------------------------------------------------------------------
// Record another usage of this term (increment the usage counter)
// ---------------------------------------------------------------------------
__save_term_usage(key, key_index + 1)
// Helper: Apply pluralization if requested
// ---------------------------------------------------------------------------
// Helper Functions
// ---------------------------------------------------------------------------
// pluralize_term(singular, plural): Returns plural form if "pl" modifier is present and available;
// otherwise returns the singular form.
let pluralize_term = (singular, plural) => {
if "pl" in modifiers and plural != none { plural } else { singular }
}
// Helper: Apply capitalization if requested
let capitalize_term = (term) => {
if "cap" in modifiers { upper(term.first()) + term.slice(1) } else { term }
}
// Helper: Apply both pluralization and capitalization
let format_term = (term, plural) => {
capitalize_term(pluralize_term(term, plural))
}
// Helper: Select and format the appropriate term form
let select_term = (is_long_mode, use_both) => {
let short_form = format_term(entry.short, entry.plural)
let long_form = if entry.long != none {
format_term(entry.long, entry.longplural)
if "pl" in modifiers and plural != none {
plural
} else {
none
}
if use_both and long_form != none {
[#long_form (#short_form)]
} else if is_long_mode and long_form != none {
[#long_form]
} else {
[#short_form]
singular
}
}
// Determine display mode from modifiers
let is_both = "both" in modifiers
let is_long = "long" in modifiers and not is_both
let is_short = "short" in modifiers and not is_both and not is_long
// capitalize_term(article, term): If "cap" is in modifiers, capitalizes the first letter
// of whichever text appears first (the article if present, otherwise the term).
// Returns a tuple (article, term) which may be modified to have uppercase first letters.
let capitalize_term = (article, term) => {
if "cap" not in modifiers {
(article, term)
} else if article == "" {
// No article present, so capitalize the term's first letter.
(article, upper(term.first()) + term.slice(1))
} else {
// Article is present; capitalize its first letter instead.
(upper(article.first()) + article.slice(1), term)
}
}
// get_term(mode): Returns the appropriate term string based on the mode.
// mode is one of "short", "long", or "both".
// - "short": Returns the short form.
// - "long": Returns the long form.
// - "both": Returns "Long form (short form)".
// We rely on prior logic to ensure that when mode = "both" or "long", a long form is available.
let get_term = (mode) => {
let short_form = pluralize_term(entry.short, entry.plural)
let long_form = pluralize_term(entry.long, entry.longplural) // none safe here
if mode == "short" {
// Just the short form.
short_form
} else if mode == "long" {
// Just the long form.
long_form
} else {
// mode == "both": "Long form (short form)".
long_form + " (" + short_form + ")"
}
}
// get_article(mode): Returns the appropriate article string based on the mode.
// - If wants_article is false, returns an empty string.
// - If mode is "short", return the short article.
// - If mode is "long" or "both", return the long article.
// The calling logic ensures that when mode = "long" or "both", a long form exists.
let get_article = (mode) => {
let wants_article = "a" in modifiers or "an" in modifiers
if not wants_article {
""
} else if mode == "short" {
entry.article + " "
} else {
// mode == "long" or "both"
entry.longarticle + " "
}
}
// determine_mode(wants_both, wants_long, wants_short, is_first_use, long_available):
// Decides which mode ("short", "long", or "both") to use.
// Preference is given to explicit modifiers. If the requested mode can't be fulfilled due to no long form,
// fall back to "short".
// If no explicit mode is given, the default behavior is:
// - On first use and if a long form exists, "both".
// - Otherwise, "short".
let determine_mode = (wants_both, wants_long, wants_short, is_first_use, long_available) => {
if wants_both {
// Explicit request for "both":
// If a long form exists, use "both", otherwise fall back to "short".
if long_available {
"both"
} else {
"short"
}
} else if wants_long {
// Explicit request for "long":
// If a long form exists, use "long", otherwise fall back to "short".
if long_available {
"long"
} else {
"short"
}
} else if wants_short {
// Explicit request for "short":
// Always "short" regardless of availability.
"short"
} else {
// No explicit mode given:
// On first use with a long form available, default to "both".
// Otherwise, use "short".
if is_first_use and long_available {
"both"
} else {
"short"
}
}
}
// ---------------------------------------------------------------------------
// Determine desired options based on modifiers and entry.long availability
// ---------------------------------------------------------------------------
let wants_both = "both" in modifiers
let wants_long = "long" in modifiers
let wants_short = "short" in modifiers
let long_available = entry.long != none
// Determine mode using the helper function
let mode = determine_mode(wants_both, wants_long, wants_short, is_first_use, long_available)
// Get the article and term for the chosen mode, then apply capitalization if requested
let (article, term) = capitalize_term(get_article(mode), get_term(mode))
// ---------------------------------------------------------------------------
// Construct and return the final output
// ---------------------------------------------------------------------------
context {
// Generate final display based on modifiers or default behavior
let display = if is_both or is_long or is_short {
select_term(is_long, is_both)
} else {
select_term(false, first)
}
// Emit term with metadata and usage label
[#display#metadata(display)#__term_label(key, key_index)]
[#article#show-term(term)#metadata(term)#__term_label(key, key_index)]
// |^^^^^^^|^^^^^^^^^ |^^^^^^^^ |^^^^^^^^^^^^
// \_art. | | |
// \_ apply user formatting function to the term
// | |
// \_ metadata lets us label (ie it's "labelable")
// |
// \_ i.e. <__gloss.key.0>, etc.
// for backlink from glossary
}
}
@@ -352,10 +462,29 @@
// Set up reference handling for glossary terms
show ref: r => {
let (key, ..modifiers) = str(r.target).split(":")
if __has_entry(key) {
show-term(__gls(key, modifiers: modifiers))
let (raw_key, ..raw_modifiers) = str(r.target).split(":")
// Determine if we need to swap the key and first modifier.
// Conditions for swapping:
// - The original key is "a" or "an" (case-insensitive),
// - That "key" does not correspond to an actual entry,
// - There is at least one modifier,
// - The first modifier corresponds to an existing entry key.
let can_swap = (lower(raw_key) == "a" or lower(raw_key) == "an") and not __has_entry(raw_key) and raw_modifiers.len() > 0 and __has_entry(raw_modifiers.first())
// If we can swap, use the first modifier as the key and insert "a" as the first modifier.
let (key, modifiers) = if can_swap {
(raw_modifiers.first(), ("a",) + raw_modifiers.slice(1))
} else {
(raw_key, raw_modifiers)
}
// Now see if this is an actual glossary term key
if __has_entry(key) {
// Found in dictionary, render via __gls()
__gls(key, modifiers: modifiers.map(lower), show-term: show-term)
} else {
// Not one of ours, so just pass it through
r
}
}
glossy/src/utils.typ
+125
View File
@@ -134,3 +134,128 @@
word + "s"
}
}
// Determines the appropriate indefinite article ("a" or "an") for a given English word.
//
// Heuristic rules:
// 1. If word looks like an acronym (all uppercase or letters separated by dots):
// - Use "an" if the first letter's name starts with a vowel sound, e.g. A (ay), E (ee), F (eff), H (aitch), I (eye), L (el), M (em), N (en), O (oh), R (ar), S (ess), X (ex).
// - Otherwise "a".
//
// 2. Otherwise, lowercase the word and apply standard rules:
// - Starts with a vowel (a, e, i, o): "an".
// - Starts with "u":
// * If it begins with "uni", "use", "user", or "eu" (e.g. "university", "use", "Europe"), we treat it as a "yoo" sound -> "a".
// * Otherwise -> "an".
// - Special silent 'h' words: if it starts with "hour", "honest", "honor", "honour", or other, use "an".
// Otherwise if starts with 'h', use "a".
// - Default: "a".
//
// Notes:
// - This is a best-effort heuristic and won't be perfect.
// - These are for singular forms. If plural form is requested alongside
// articles, the caller should panic before calling this function.
//
// Returns:
// "a" or "an"
//
// Example:
// __determine_article("RF") -> "an" (Ar-Ef)
// __determine_article("radio") -> "a"
// __determine_article("hour") -> "an"
// __determine_article("honest") -> "an"
// __determine_article("university") -> "a"
// __determine_article("umbrella") -> "an"
// __determine_article("Europe") -> "a" (because we assume "yoo-ruhp")
#let __determine_article(word) = {
// Check input
if word == none or word.trim() == "" {
// If invalid, default to none
return none
}
// Normalize the word
let upper_word = word.trim()
let lower_word = lower(upper_word)
// When these letters are spelled out, they get an "an" (i.e. "an RFC")
let acronym_vowels = (
"A", // "ay"
"E", // "ee"
"F", // "eff"
"H", // "aitch"
"I", // "eye"
"L", // "el"
"M", // "em"
"N", // "en"
"O", // "oh"
"R", // "ar"
"S", // "ess"
"X", // "ex"
)
// Helper to detect if word looks like an acronym
let is_acronym = {
// All uppercase or letters separated by non-alphabetical chars
let cleaned = upper_word.replace(".", "").replace("-", "")
cleaned.codepoints().all(c => c == upper(c)) and cleaned.len() > 0
}
if is_acronym {
// Use acronym rules
let first_char = upper_word.slice(0,1)
if acronym_vowels.contains(first_char) {
"an"
} else {
"a"
}
} else {
// Non-acronym rules
let first_char = lower_word.slice(0,1)
// Special cases for words matching a set of known 'silent h' prefixes
let silent_h_words = (
"heir", // "air"
"herb", // "erb" (in American English)
"homage", // "oh-mij" or "ah-mij"
"honest", // "on-est"
"honor", // "on-or" (American English)
"honour", // "on-our" (British English)
"hour", // "our"
)
if silent_h_words.any(w => lower_word.starts-with(w)) {
return "an"
}
// Words starting with 'eu', which has the 'yoo' sound
if lower_word.starts-with("eu") {
return "a"
}
// Words starting with 'u', that get the 'yoo' sound
if first_char == "u" {
let yoo_sounds = (
"ubi", // ubiquitous
"uni", // unicycle, uniform, universe, university, unilateral, unique, union, etc.
"usa", // usage, usability
"use", // use, useful, useless
"usu", // usual, usually
"usur", // usurp
"ute", // utensil, uterus
"uti", // utility, utilize, utilization
"uto", // utopia, utopian
)
if yoo_sounds.any(w => lower_word.starts-with(w)) {
return "a"
}
}
// Vowel start
if "aeiou".contains(first_char) {
return "an"
}
// the default case, plus 'h' words not in the silent list
"a"
}
}