Commit `70dc5827f4`

70dc5827f43c0191692808873a7abfe825950f79

parent: ef9a625b5d

Verified · cmc

cmc <hello@cleberg.net> · 2026-08-30 06:53 UTC

audit: an unlisted keyword is pass-through, not a blind spot (#2)

The census legend said `???` marks "a name the implementation does not
recognize at all". On orgo's own docs it marked `LEDE`, which the shipped docs
template reads as `page.keywords.lede`, `themes/docs.css` styles, and
`docs/guide/02-configuration.org` documents.

Reaching templates as `page.keywords.<name>` is the designed behaviour, so
every keyword name works and none is a blind spot; `???` on one was a statement
about orgo's source, not about the corpus. Which keywords have dedicated
handling is still worth reporting, so the distinction stays and the marker
changes: `—` for pass-through, `???` reserved for drawers and link schemes,
where an unlisted name has no such fallback.

`is_known` becomes `marker`, which returns the report's marker directly. The
marker column is now a consistent four columns wide — `??? ` was one wider than
the blank it replaced, so flagged rows sat a character right of the rest.

Closes #2

Layout: unified · split

docs/guide/09-auditing.org +9 −3

 coverage: 9002 in-scope use(s) (100.0%), 0 out-of-scope (0.0%)
 KEYWORDS
-   SLUG                                  180     180  blog/2018-11-28-aes-encryption.org:4
+    SLUG                                 180     180  blog/2018-11-28-aes-encryption.org:4
-   TITLE                                 180     180  blog/2018-11-28-aes-encryption.org:2
+    TITLE                                180     180  blog/2018-11-28-aes-encryption.org:2
+—   LEDE                                  14      14  blog/2018-11-28-aes-encryption.org:3
 ...
 #+END_EXAMPLE
 - The *coverage* line is the number to look at first.
 - =???= marks a name orgo does not recognise at all. That is the blind-spot signal —
   not "known unsupported", but unknown — and this corpus has none. Block names never
-  carry it: an unrecognised one is still a special block, and still renders.
+  carry it: an unrecognised one is still a special block, and still renders. Keyword
+  names never carry it either — see below.
+- =—= marks a keyword with no dedicated handling. It is not a gap: the keyword reaches
+  your layout as ={{ page.keywords.<name> }}=, which is the designed behaviour, so the
+  marker tells you which of your keywords orgo reads by name and which rely on that
+  pass-through.
 Four censuses follow the construct table: every distinct =#+KEYWORD:=, block type,
 drawer name and link scheme in the corpus. A =???= in any of them is worth a look.

fixtures/audit-keywords.org added +5

@@ -0,0 +1,5 @@
	1	#+TITLE: Keyword census
	2	#+LEDE: A keyword the shipped docs template reads.
	3	#+PROJECT_STATUS: A keyword nothing reads by name.
	4
	5	Body text.

src/audit.rs +34 −18

     pub link_schemes: BTreeMap<String, Tally>,
 }
-/// Names the implementation understands, so the census can flag everything else. These
+/// Names the implementation reads by name, so the census can mark everything else. These
-/// are the *recognized* sets, not the supported ones: `INCLUDE` is recognized (it is
+/// are the *recognized* sets, not the supported ones: `INCLUDE` is recognized and
-/// deliberately inert) while an unlisted keyword is a genuine blind spot.
+/// deliberately inert.
 const KNOWN_KEYWORDS: &[&str] = &[
     "TITLE", "AUTHOR", "DATE", "EMAIL", "LANGUAGE", "OPTIONS", "FILETAGS", "DESCRIPTION",
     "KEYWORDS", "CAPTION", "NAME", "ATTR_HTML", "RESULTS", "TBLFM", "INCLUDE", "TODO",
     "relative",
 ];
+/// The census markers. A name with dedicated handling carries none; `PASS_THROUGH` says
+/// nothing reads the name but it works anyway; `UNKNOWN` is the blind-spot signal.
+const HANDLED: &str = "";
+const PASS_THROUGH: &str = "\u{2014}";
+const UNKNOWN: &str = "???";
 impl Audit {
-    /// Is this name one the implementation recognizes?
+    /// How the report marks a census name: the recognized set to look the name up in,
-    pub fn is_known(kind: Census, name: &str) -> bool {
+    /// and what an unlisted name means for that census.
-        let known = match kind {
+    pub fn marker(kind: Census, name: &str) -> &'static str {
-            Census::Keyword => KNOWN_KEYWORDS,
+        let (known, unlisted) = match kind {
+            // An unlisted keyword is not a blind spot. Reaching templates as
+            // `page.keywords.<name>` is the designed behaviour, so every keyword name
+            // works; what the census reports is which ones have dedicated handling.
+            // `LEDE`, read by the shipped docs theme's template, was the case that made
+            // this concrete: `???` on it was a claim about orgo's source, not a gap.
+            Census::Keyword => (KNOWN_KEYWORDS, PASS_THROUGH),
             // Every block name renders, and renders as org renders it: the names in
             // `block_construct` through dedicated handling, every other name as a special
             // block — a div carrying the name, holding parsed org, which is exactly what
             // org's exporter emits. No block name is a blind spot.
-            Census::Block => return true,
+            Census::Block => return HANDLED,
-            Census::Drawer => KNOWN_DRAWERS,
+            Census::Drawer => (KNOWN_DRAWERS, UNKNOWN),
-            Census::Scheme => KNOWN_SCHEMES,
+            Census::Scheme => (KNOWN_SCHEMES, UNKNOWN),
         };
-        known.iter().any(|k| k.eq_ignore_ascii_case(name))
+        if known.iter().any(|k| k.eq_ignore_ascii_case(name)) {
+            HANDLED
+        } else {
+            unlisted
+        }
     }
 }
         names.sort_by(|a, b| b.1.occurrences.cmp(&a.1.occurrences).then(a.0.cmp(b.0)));
         out.push_str(&format!("\n{title}\n"));
         for (name, tally) in names {
-            let flag = if Audit::is_known(kind, name) {
-                "   "
-            } else {
-                "??? "
-            };
             out.push_str(&format!(
-                "{flag}{:<32} {:>8} {:>7}  {}\n",
+                "{:<4}{:<32} {:>8} {:>7}  {}\n",
+                Audit::marker(kind, name),
                 name,
                 tally.occurrences,
                 tally.files,
             ));
         }
     }
-    out.push_str("\n`???` marks a name the implementation does not recognize at all.\n");
+    out.push_str(
+        "\n`???` marks a name the implementation does not recognize at all.\n\
+         `\u{2014}` marks a keyword with no dedicated handling; it reaches templates \
+         as `page.keywords.<name>`.\n",
+    );
     out
 }

tests/constructs.rs +17

	@@ -859,3 +859,20 @@ fn audit_ignores_constructs_inside_verbatim() {
859	);	859	);
860	}	860	}
861	}	861	}
		862
		863	/// An unlisted keyword is not a blind spot: reaching templates as `page.keywords.<name>`
		864	/// is the designed behaviour, so it is marked as pass-through rather than `???`, which
		865	/// claims orgo does not recognise the name at all.
		866	#[test]
		867	fn audit_marks_unhandled_keywords_as_pass_through() {
		868	let report = audit_fixture("audit-keywords.org");
		869	for name in ["LEDE", "PROJECT_STATUS"] {
		870	let line = report.lines().find(\|l\| l.contains(name)).expect("the keyword is censused");
		871	assert!(
		872	line.starts_with('\u{2014}'),
		873	"a keyword that reaches templates must not read as a blind spot:\n{line}"
		874	);
		875	}
		876	let flagged: Vec<&str> = report.lines().filter(\|l\| l.starts_with("???")).collect();
		877	assert!(flagged.is_empty(), "no keyword name is unrecognised: {flagged:?}");
		878	}

Commit 70dc5827f4

Commit `70dc5827f4`