@airmark/quiver 0.32.1 → 0.33.0

package/quills/usaf_memo/0.3.0/packages/tonguetoquill-usaf-memo/src/body.typ

@@ -1,16 +1,9 @@
-// body.typ: Paragraph body rendering for USAF memorandum sections
-//
-// This module implements the visual rendering of AFH 33-337 compliant
-// paragraph bodies with proper numbering, nesting, and formatting.
+// Paragraph numbering, nesting, and indentation for the memorandum body.
 
 #import "config.typ": *
 #import "utils.typ": *
 #import "primitives.typ": render-memo-table
 
-// =============================================================================
-// PARAGRAPH NUMBERING UTILITIES
-// =============================================================================
-
 /// Gets the numbering format for a specific paragraph level.
 ///
 /// - level (int): Paragraph nesting level (0-based)
@@ -52,7 +45,6 @@
   daf-paragraph.nested-first-level-indent + (level - 1) * daf-paragraph.nested-step
 }
 
-/// Resets counter entries from `start` upward to 1 in the level-counts dictionary.
 #let reset-levels-from(level-counts, start, max-levels) = {
   for child in range(start, max-levels) {
     level-counts.insert(str(child), 1)
@@ -101,15 +93,16 @@
   }
 }
 
-// =============================================================================
-// PARAGRAPH BODY RENDERING
-// =============================================================================
-// AFH 33-337 "The Text of the Official Memorandum" §1-12 specifies:
-// - Single-space text, double-space between paragraphs
-// - Number and letter each paragraph and subparagraph
-// - "A single paragraph is not numbered" (§2)
-// - First paragraph flush left, never indented
-// - Indent sub-paragraphs to align with first character of parent paragraph text
+// AFH 33-337 "The Text of the Official Memorandum" §1-12: number and letter
+// each paragraph and subparagraph as 1. / a. / (1) / (a); leave a top-level
+// paragraph flush left and a lone paragraph unnumbered (§2); indent each
+// subparagraph to align with the first character of its parent's text.
+//
+// Rendering takes two passes. The first lays the content out hidden, so that
+// Typst's own show rules resolve, and buffers each paragraph, table, and block
+// quote with the nesting level it was found at. The second emits the buffer,
+// where those show rules are out of scope and numbering can be assigned in
+// document order.
 #let render-body(content, memo-style: "usaf") = {
   let PAR_BUFFER = state("PAR_BUFFER")
   PAR_BUFFER.update(())
@@ -125,72 +118,63 @@
   let ITEM_FIRST_PAR = state("ITEM_FIRST_PAR")
   ITEM_FIRST_PAR.update(false)
 
-  // The first pass parses paragraphs, list items, etc. into standardized arrays
-  let first_pass = {
-    // Collect pars with nesting level
+  let first-pass = {
     show par: p => context {
-      let nest_level = NEST_DOWN.get().at(0) - NEST_UP.get().at(0)
-      let is_heading = IS_HEADING.get()
-      let is_first_par = ITEM_FIRST_PAR.get()
+      let nest-level = NEST_DOWN.get().at(0) - NEST_UP.get().at(0)
+      let is-heading = IS_HEADING.get()
+      let is-first-par = ITEM_FIRST_PAR.get()
 
       // Determine if this is a continuation block within a multi-block list item.
-      // A continuation is a non-first paragraph inside a list item (nest_level > 0).
-      let is_continuation = nest_level > 0 and not is_first_par
+      // A continuation is a non-first paragraph inside a list item (nest-level > 0).
+      let is-continuation = nest-level > 0 and not is-first-par
 
       PAR_BUFFER.update(pars => {
         pars.push((
           content: text([#p.body]),
-          nest_level: nest_level,
-          kind: if is_heading { "heading" } else if is_continuation { "continuation" } else { "par" },
+          nest-level: nest-level,
+          kind: if is-heading { "heading" } else if is-continuation { "continuation" } else { "par" },
         ))
         pars
       })
 
       // After the first paragraph of a list item, mark subsequent ones as continuations
-      if nest_level > 0 and is_first_par {
+      if nest-level > 0 and is-first-par {
         ITEM_FIRST_PAR.update(false)
       }
 
       p
     }
-    // Collect tables — captured as-is without paragraph numbering
+    // Tables are buffered whole; nothing inside one takes a paragraph number.
     show table: t => context {
       PAR_BUFFER.update(pars => {
         pars.push((
           content: t,
-          nest_level: -1,
+          nest-level: -1,
           kind: "table",
         ))
         pars
       })
       t
     }
-    // Collect block quotes — captured as-is, with paragraph processing kept
-    // out of them. AFH 33-337 numbers paragraphs and letters subparagraphs, and
-    // a body sometimes has to hold lines that are neither: a roster of names, a
-    // quoted passage, an address. The block quote is where an author says so —
-    // its content is emitted verbatim, so nothing inside it takes a number, a
-    // letter, or a bullet.
+    // AFH 33-337 numbers paragraphs and letters subparagraphs, and a body
+    // sometimes has to hold lines that are neither: a roster of names, a quoted
+    // passage, an address. The block quote is where an author says so — its
+    // content reaches the page verbatim, taking no number, letter, or bullet.
     //
     // Returning `none` rather than the quote is what makes that true: the
     // quote's own paragraphs are never laid out here, so the `show par` above
     // never sees them and cannot number them. The buffered body is emitted in
     // the second pass, where these show rules are out of scope. Typst's own
-    // block-quote framing (padding, attribution) is dropped with the element;
-    // what reaches the page is the author's lines and nothing else.
+    // block-quote framing (padding, attribution) is dropped with the element.
     //
     // The nesting level rides along so a quote inside a list item lines up with
-    // that item's text (see the emission below). @quillmark/wasm 0.109.0 is
-    // what makes that level trustworthy: before it, a container inside a list
-    // item opened at column 0 and terminated the list, so a quote's siblings
-    // came back as top-level paragraphs (#123). It now nests, and this quill
-    // stopped declining the construct with it.
+    // that item's text (see the emission below).
     show quote.where(block: true): q => context {
-      let nest_level = NEST_DOWN.get().at(0) - NEST_UP.get().at(0)
+      let nest-level = NEST_DOWN.get().at(0) - NEST_UP.get().at(0)
       PAR_BUFFER.update(pars => {
         pars.push((
           content: q.body,
-          nest_level: nest_level,
+          nest-level: nest-level,
           kind: "quote",
         ))
         pars
@@ -204,9 +188,9 @@
         IS_HEADING.update(false)
       }
 
-      // Convert list/enum items to pars
-      // Note: No context wrapper here - state updates don't need it and cause
-      // layout convergence issues with many list items
+      // List and enum items become paragraphs carrying a nesting level. No
+      // `context` wrapper: state updates do not need one, and one here fails
+      // to converge on a body with many list items.
       show enum.item: it => {
         NEST_DOWN.step()
         ITEM_FIRST_PAR.update(true)
@@ -221,9 +205,9 @@
       }
 
       {
-        // Typst bug bandaid:
-        // `show par` will not collect wrappers unless there is content outside
-        // Add zero width space to always have content outside of wrapper
+        // `show par` does not capture an element that fills its paragraph
+        // whole, so a zero-width space follows each wrapper to keep some
+        // content outside it.
         show strong: it => {
           [#it#sym.zws]
         }
@@ -241,31 +225,30 @@
     }
   }
   // Use place() to prevent hidden content from affecting layout flow
-  place(hide(first_pass))
+  place(hide(first-pass))
 
   // Second pass: consume par buffer
   //
   // PAR_BUFFER item dictionary layout:
   //   item.content    — the paragraph body, table element, or block-quote body
-  //   item.nest_level — nesting depth (−1 for tables)
+  //   item.nest-level — nesting depth (−1 for tables)
   //   item.kind       — "par", "heading", "table", "continuation", or "quote"
   context {
-    let heading_buffer = none
-    let heading_level = 0
-    // Filter out zero-width paragraphs so that an empty body (e.g. empty
-    // string from a KIND with no text) emits nothing and collapses to zero
-    // vertical space. Tables are always kept regardless of measured width.
+    let heading-buffer = none
+    let heading-level = 0
+    // Zero-width paragraphs are dropped, so an empty body emits nothing and
+    // collapses to zero vertical space. A table is kept whatever it measures.
     let items = PAR_BUFFER.get().filter(item =>
       item.kind == "table" or measure(item.content).width > 0pt
     )
     if items.len() == 0 { return }
     // Only top-level paragraphs count for AFH 33-337 §2 numbering purposes
-    let par_count = items.filter(item => item.kind == "par").len()
-    let total_count = items.len()
+    let par-count = items.filter(item => item.kind == "par").len()
+    let total-count = items.len()
 
-    // Track paragraph numbers per level manually to avoid nested-context
-    // counter propagation issues.  Dictionary maps level index (as string)
-    // to the current counter value at that level.
+    // Numbers are tracked in a dictionary keyed by level index (as a string)
+    // rather than in counters, whose updates do not propagate out of the
+    // nested contexts this loop runs in.
     let max-levels = paragraph-config.numbering-formats.len()
     let level-counts = (:)
     for lvl in range(max-levels) {
@@ -273,56 +256,55 @@
     }
 
     let i = 0
-    let any_emitted = false
+    let any-emitted = false
     for item in items {
       i += 1
       let kind = item.kind
-      let item_content = item.content
+      let item-content = item.content
 
       // A buffered heading runs into this element only when the two belong to
       // the same item: a later block of this list item ("continuation"), or,
       // at top level, the next paragraph. The first block of the *next* item,
-      // a table (nest_level −1, so the level test alone excludes it), a block
+      // a table (nest-level −1, so the level test alone excludes it), a block
       // quote (verbatim: a heading prepended to it would be ink the author did
       // not put inside the quote), and another heading all fail the test, and
       // each would otherwise carry the heading's text somewhere it was not
       // authored. Those emit the heading on its own line, the treatment a
       // heading before a table takes.
-      if heading_buffer != none {
-        let runs_in = (
+      if heading-buffer != none {
+        let runs-in = (
           kind not in ("heading", "quote")
-            and item.nest_level == heading_level
-            and (heading_level == 0 or kind == "continuation")
+            and item.nest-level == heading-level
+            and (heading-level == 0 or kind == "continuation")
         )
-        if runs_in {
-          item_content = [#strong[#heading_buffer.] #item_content]
+        if runs-in {
+          item-content = [#strong[#heading-buffer.] #item-content]
         } else {
-          if any_emitted { blank-line() }
-          strong[#heading_buffer.]
-          any_emitted = true
+          if any-emitted { blank-line() }
+          strong[#heading-buffer.]
+          any-emitted = true
         }
-        heading_buffer = none
+        heading-buffer = none
       }
 
       // Buffer this heading for the next element to run into. The level it was
       // captured at rides along: the run-in test needs it, and the buffer is
       // read one iteration later, by which time `item` is the *next* element.
       if kind == "heading" {
-        heading_buffer = item_content
-        heading_level = item.nest_level
+        heading-buffer = item-content
+        heading-level = item.nest-level
         continue
       }
 
-      // Format based on element kind
-      let nest_level = item.nest_level
+      let nest-level = item.nest-level
       let indent-fn = if memo-style == "daf" {
         (level, _counts) => calculate-daf-indent(level)
       } else {
         (level, counts) => calculate-indent-from-counts(level, counts)
       }
-      let final_par = {
+      let final-par = {
         if kind == "table" {
-          render-memo-table(item_content)
+          render-memo-table(item-content)
         } else if kind == "quote" {
           // A block quote is the body's unlabeled block: no number, no letter,
           // no bullet — the author's lines as written. It is placed, not
@@ -348,40 +330,39 @@
           // body puts between its own paragraphs — keeps that break visible.
           let quoted = {
             set par(spacing: spacing.line + line-stride())
-            item_content
+            item-content
           }
-          let offset = paragraph-text-offset(nest_level, level-counts, indent-fn)
+          let offset = paragraph-text-offset(nest-level, level-counts, indent-fn)
           if offset == 0pt { quoted } else { pad(left: offset, quoted) }
         } else if kind == "continuation" {
           // Continuation block within a multi-block list item:
           // indent to align with preceding numbered paragraph's text, no new number.
           // level-counts still holds the value of the preceding numbered paragraph.
-          if memo-style == "daf" and nest_level == 0 {
-            item_content
+          if memo-style == "daf" and nest-level == 0 {
+            item-content
           } else {
-            format-par(item_content, nest_level, level-counts, indent-fn, continuation: true)
+            format-par(item-content, nest-level, level-counts, indent-fn, continuation: true)
           }
         } else if memo-style == "daf" {
-          if nest_level > 0 {
-            let par = format-par(item_content, nest_level, level-counts, indent-fn)
-            level-counts.insert(str(nest_level), level-counts.at(str(nest_level), default: 1) + 1)
-            level-counts = reset-levels-from(level-counts, nest_level + 1, max-levels)
+          if nest-level > 0 {
+            let par = format-par(item-content, nest-level, level-counts, indent-fn)
+            level-counts.insert(str(nest-level), level-counts.at(str(nest-level), default: 1) + 1)
+            level-counts = reset-levels-from(level-counts, nest-level + 1, max-levels)
             par
           } else {
             // DAF top-level paragraphs are unnumbered and first-line indented.
             // Reset nested counters so each new top-level paragraph restarts children.
             level-counts = reset-levels-from(level-counts, 0, max-levels)
-            [#h(daf-paragraph.top-first-line-indent)#item_content]
+            [#h(daf-paragraph.top-first-line-indent)#item-content]
           }
-        } else if par_count > 1 {
-          // Apply paragraph numbering per AFH 33-337 §2
-          let par = format-par(item_content, nest_level, level-counts, indent-fn)
-          level-counts.insert(str(nest_level), level-counts.at(str(nest_level)) + 1)
-          level-counts = reset-levels-from(level-counts, nest_level + 1, max-levels)
+        } else if par-count > 1 {
+          let par = format-par(item-content, nest-level, level-counts, indent-fn)
+          level-counts.insert(str(nest-level), level-counts.at(str(nest-level)) + 1)
+          level-counts = reset-levels-from(level-counts, nest-level + 1, max-levels)
           par
         } else {
           // AFH 33-337 §2: "A single paragraph is not numbered"
-          item_content
+          item-content
         }
       }
 
@@ -391,9 +372,9 @@
       // `context { for … }` block, where it does not combine with the
       // preceding header section's block-spacing the same way as a
       // top-level blank-line() call.
-      if any_emitted { blank-line() }
-      any_emitted = true
-      if i == total_count {
+      if any-emitted { blank-line() }
+      any-emitted = true
+      if i == total-count {
         // AFH 33-337 "Signature Block": "Do not place the signature element on a
         // continuation page by itself." The signature block that follows has no
         // keep-with-previous of its own — Typst has no such property — so the
@@ -405,8 +386,8 @@
         // ordinary mid-paragraph break into a wholesale jump. A third of the
         // text block covers what a memorandum actually ends on — a closing
         // paragraph, a short table — while leaving the long block to be divided
-        // by the break as before, which leaves its own tail on the continuation
-        // page for the signature to sit under.
+        // by the break, which leaves its own tail on the continuation page for
+        // the signature to sit under.
         //
         // The budget is a fixed fraction rather than the space actually left
         // below this element, which is the question one would rather ask. A
@@ -415,26 +396,16 @@
         // the top of the page, so every element measures as fitting and
         // relocates — and from the top of its new page the same test agrees, so
         // the wrong answer is a fixed point that later passes never revisit.
-        //
-        // (The superseded rule was sticky under four lines, reading §11 — "avoid
-        // dividing a paragraph of less than four lines between two pages" — as
-        // if it governed the signature. It does not; it governs how a paragraph
-        // may be divided. All the four-line gate did was leave every body ending
-        // in a longer paragraph, or in a table, free to strand its signature.)
-        let available_width = page.width - spacing.margin * 2
-        let relocation_budget = (page.height - spacing.margin * 2) / 3
-        let element_height = measure(final_par, width: available_width).height
-        block(sticky: element_height <= relocation_budget)[#final_par]
+        let available-width = page.width - spacing.margin * 2
+        let relocation-budget = (page.height - spacing.margin * 2) / 3
+        let element-height = measure(final-par, width: available-width).height
+        block(sticky: element-height <= relocation-budget)[#final-par]
       } else {
-        // Wrap every non-last emission in a plain block so the document-wide
-        // `set block(above: spacing.line)` rule contributes the same 0.5em
-        // gap above every paragraph, including the first (matching the
-        // single-paragraph case which always passes through the
-        // `i == total_count` branch) and middle paragraphs (so the gap
-        // between the 1st and 2nd doesn't shrink relative to the gap
-        // between the 2nd-to-last and last). Bare emission would skip
-        // `block.above` entirely and visibly compress the spacing.
-        block[#final_par]
+        // A plain block, so that the document-wide `set block(above:
+        // spacing.line)` contributes the same 0.5em above every paragraph as it
+        // does above the last one. A bare emission skips `block.above` and
+        // visibly compresses the gap.
+        block[#final-par]
       }
     }
 
@@ -442,9 +413,9 @@
     // dies with the loop unless it is drained here. Sticky for the same reason
     // the last item is: a standalone heading is one line, so it keeps with the
     // signature block rather than opening a page alone.
-    if heading_buffer != none {
-      if any_emitted { blank-line() }
-      block(sticky: true)[#strong[#heading_buffer.]]
+    if heading-buffer != none {
+      if any-emitted { blank-line() }
+      block(sticky: true)[#strong[#heading-buffer.]]
     }
   }
 }

package/quills/usaf_memo/0.3.0/packages/tonguetoquill-usaf-memo/src/config.typ

@@ -1,42 +1,24 @@
-// config.typ: Configuration constants and defaults for USAF memorandum template
-//
-// This module defines core configuration values that implement AFH 33-337 Chapter 14
-// formatting requirements for official USAF memorandums.
-
-// =============================================================================
-// SPACING CONSTANTS
-// =============================================================================
-// AFH 33-337 specifies precise spacing requirements throughout Chapter 14
+// Spacing, typography, and color constants for the memorandum layout.
 
 #let spacing = (
-  line: .5em, // Internal line spacing for readability (`par.leading`; gap between line boxes)
+  line: .5em, // `par.leading`: the gap between line boxes
   tab: 0.5in, // Tab stop for multi-column recipient alignment
   margin: 1in, // AFH 33-337 §4: "Use 1-inch margins on the left, right and bottom"
 )
 
-// =============================================================================
-// TYPOGRAPHY DEFAULTS
-// =============================================================================
-// AFH 33-337 §5: "Use 12 point Times New Roman font for text"
-
 #let DEFAULT_LETTERHEAD_FONTS = ("Copperplate CC", "NimbusRomNo9L")
-#let DEFAULT_BODY_FONTS = ("NimbusRomNo9L",)  // AFH 33-337 §5: Times New Roman required; NimbusRomNo9L is a metric-compatible clone
-// Static monospace face for raw/code text. Liberation Mono is metric-compatible with
-// Courier New; only the regular weight is bundled (no bold or italic variants).
+// AFH 33-337 §5: "Use 12 point Times New Roman font for text". NimbusRomNo9L is
+// a metric-compatible clone of it; Liberation Mono, which sets raw text, is one
+// of Courier New and carries its regular weight alone.
+#let DEFAULT_BODY_FONTS = ("NimbusRomNo9L",)
 #let DEFAULT_MONO_FONTS = ("Liberation Mono",)
-#let LETTERHEAD_COLOR = rgb("#355e93")  // Faded USAF blue for letterhead
-
-// =============================================================================
-// PARAGRAPH CONFIGURATION
-// =============================================================================
-// AFH 33-337 "The Text of the Official Memorandum" §2:
-// "Number and letter each paragraph and subparagraph"
-// Hierarchical numbering: 1., a., (1), (a), etc.
+#let LETTERHEAD_COLOR = rgb("#355e93")  // Faded USAF blue
 
+// AFH 33-337 "The Text of the Official Memorandum" §2: "Number and letter each
+// paragraph and subparagraph". The spec gives four levels; deeper nesting falls
+// back to an underlined bare number.
 #let paragraph-config = (
   counter-prefix: "par-counter-",
-  // AFH 33-337 §2: Hierarchical paragraph numbering format
-  // Level 0: 1., 2., 3. | Level 1: a., b., c. | Level 2: (1), (2), (3) | Level 3: (a), (b), (c)
   numbering-formats: ("1.", "a.", "(1)", "(a)", n => underline(str(n)), n => underline(str(n))),
 )
 
@@ -48,27 +30,12 @@
   nested-step: 0.5in,
 )
 
-// =============================================================================
-// COUNTERS
-// =============================================================================
-
 #let counters = (
   indorsement: counter("indorsement"),
 )
 
-// =============================================================================
-// CLASSIFICATION COLORS
-// =============================================================================
-// AFH 33-337 §3: "Follow AFI 31-401, Information Security Program Management,
-// applicable executive orders and DoD guidance for the necessary markings on
-// classified correspondence."
-// Color values follow DoD/CAPCO standard classification marking colors:
-//   - TOP SECRET: orange  (#FF671F)
-//   - SECRET: red         (#C8102E)
-//   - CONFIDENTIAL: black (per project style guide)
-//   - CUI: black          (DoDM 5200.48; per project style guide)
-//   - UNCLASSIFIED: green (#007A33)
-
+// DoD/CAPCO standard marking colors, except CONFIDENTIAL and CUI, which this
+// template sets black.
 #let CLASSIFICATION_COLORS = (
   "TOP SECRET": rgb(255, 103, 31),
   "SECRET": rgb(200, 16, 46),