outline

CHANGELOG.md

@@ -12,6 +12,26 @@
 > definition, whereas the long in `#gls(...)` refers to the "long form" of the
 > entry's output.
 
+> [!TIP]
+> New options have been added to `make-glossary` to control which
+> elements always use the "first form" of an entry.
+> Previously, usages in outlines, figure captions and headings were
+> contextual. That is, the form used depended on whether the entry
+> had been used before in the document.
+> Now, these elements can be configured independently to be either always first (`true`),
+> dynamic (`none`) or always the short form (`false`).
+>
+> The default configuration is to always use the first form.
+>
+> ```typ
+> #show: make-glossary.with(
+>   always-first: none,
+>   outline-always-first: true,
+>   figure-caption-always-first: true,
+>   heading-always-first: true,
+> )
+> ```
+
 > [!TIP]
 > A new utility `print-gloss` has been added to allow printing the default's
 > formatting for a single entry. This is useful when you want to print

tests/outline-figure-caption-heading-always-first/.gitignore

@@ -0,0 +1,4 @@
+# generated by tytanic, do not edit
+
+diff/**
+out/**

tests/outline-figure-caption-heading-always-first/test.typ

@@ -0,0 +1,86 @@
+#import "../../themes/default.typ": *
+
+#let entry-list(n) = (
+  (
+    key: str((n - 1) * 3 + 1),
+    long: lorem((n - 1) * 3 + 1).slice(0, -1).replace(" ", ""),
+  ),
+  (
+    key: str((n - 1) * 3 + 2),
+    long: lorem((n - 1) * 3 + 2).slice(0, -1).replace(" ", ""),
+  ),
+  (
+    key: str((n - 1) * 3 + 3),
+    long: lorem((n - 1) * 3 + 3).slice(0, -1).replace(" ", ""),
+  ),
+)
+
+#set page(paper: "a5")
+#register-glossary(entry-list(1) + entry-list(2) + entry-list(3))
+
+== Test: outline-always-first
+
+#{
+  show: make-glossary.with(
+    outline-always-first: true,
+  )
+
+  outline(target: figure, title: "Figures")
+  figure([`outline-always-first: true`], caption: [@1])
+}
+
+#{
+  show: make-glossary.with(
+    outline-always-first: false,
+  )
+
+  outline(target: figure, title: "Figures")
+  figure([`outline-always-first: false`], caption: [@2])
+}
+
+== Test: figure-caption-always-first
+
+#{
+  show: make-glossary.with(
+    figure-caption-always-first: true,
+  )
+
+  figure([`figure-caption-always-first: true`], caption: [@3])
+}
+
+#{
+  show: make-glossary.with(
+    figure-caption-always-first: false,
+  )
+
+  figure([`figure-caption-always-first: false`], caption: [@4])
+}
+
+== Test: heading-always-first
+
+#{
+  show: make-glossary.with(
+    heading-always-first: true,
+  )
+
+  [=== `heading-always-first: true` @5]
+}
+
+#{
+  show: make-glossary.with(
+    heading-always-first: false,
+  )
+
+  [=== `heading-always-first: false` @6]
+}
+
+#pagebreak()
+= Glossary
+
+#show: make-glossary
+#print-glossary(
+  (entry-list(1) + entry-list(2) + entry-list(3)),
+  show-all: true,
+  disable-back-references: true,
+)
+

themes/default.typ

@@ -1100,6 +1100,9 @@
   body,
   link: true,
   always-first: none,
+  outline-always-first: true,
+  figure-caption-always-first: true,
+  heading-always-first: true,
   user-capitalize: default-capitalize,
   user-plural: default-plural,
 ) = {
@@ -1114,6 +1117,27 @@
     user-capitalize: user-capitalize,
     user-plural: user-plural,
   )
+  show outline: it => {
+    show ref: refrule.with(
+      update: false,
+      first: outline-always-first,
+    )
+    it
+  }
+  show figure.caption: it => {
+    show ref: refrule.with(
+      update: false,
+      first: figure-caption-always-first,
+    )
+    it
+  }
+  show heading: it => {
+    show ref: refrule.with(
+      update: false,
+      first: heading-always-first,
+    )
+    it
+  }
   body
 }