Commit `f274b51656`

f274b516569365d352ed75206f6678f862cfd7f7

parent: ce3f2623d5

Unregistered key

cmc <hello@cleberg.net> · 2026-08-23 05:05 UTC
committer: <noreply@github.com>

Point scope references at the org-support guide (#29)

Ten comments cited `README §"v1 scope"` or `README §OUT`. README.md has no
such section — that content now lives in `docs/guide/05-org-support.org`, which
README links to from the docs table. The citations now name that file, and the
"v1" phrasing goes with them, since nothing defines a v1 scope line any more.

Two claims in `parser.rs`'s header were stale as of #27 and #28: unknown block
types do not "keep their content verbatim as example blocks" — they render as
special blocks holding parsed org — and `#+TBLFM:` is no longer described as
out of scope.

Adding the section back to README instead would put the supported/unsupported
list in two places, which is how these drifted apart to begin with.

Layout: unified · split

fixtures/outofscope.org +3 −2

	@@ -1,8 +1,9 @@
1	#+TITLE: Out of Scope	1	#+TITLE: Out of Scope
2	#+INCLUDE: "other.org"	2	#+INCLUDE: "other.org"
3		3
4	Every construct here is on the README's explicit OUT list. The contract is not that we	4	Every construct here is on the explicit "Not supported" list in the org-support guide.
5	handle them — it is that they degrade predictably and never crash the build.	5	The contract is not that we handle them — it is that they degrade predictably and never
		6	crash the build.
6		7
7	* Babel	8	* Babel
8		9

src/audit.rs +8 −7

 //! Corpus audit (spec §5, Phase 0): measure which org constructs a real corpus actually
-//! uses, and classify each against the v1 IN/OUT line.
+//! uses, and classify each against the supported/unsupported line.
 //!
-//! This exists because the v1 scope was, on the README's own admission, *recommended*
+//! This exists because the scope was recommended rather than measured — a guess about
-//! rather than measured — a guess about which slice of org matters. A guess about a
+//! which slice of org matters. A guess about a corpus is a hypothesis, and this is the
-//! corpus is a hypothesis, and this is the experiment. It answers two questions:
+//! experiment. It answers two questions:
 //!
 //! 1. **Coverage** — of the constructs this corpus uses, which do we handle? A construct
 //!    that is common here and out of scope is a scope bug, not a corpus quirk.
 use camino::{Utf8Path, Utf8PathBuf};
 use walkdir::WalkDir;
-/// Where a construct sits relative to the v1 scope line (README §"v1 scope").
+/// Where a construct sits relative to the supported set, which
+/// `docs/guide/05-org-support.org` defines.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
 pub enum Scope {
-    /// v1 handles this.
+    /// orgo handles this.
     In,
-    /// v1 deliberately excludes this; it degrades predictably.
+    /// orgo deliberately excludes this; it degrades predictably.
     Out,
 }

src/main.rs +2 −2

	@@ -90,8 +90,8 @@ enum Command {
90	/// Output directory to remove.	90	/// Output directory to remove.
91	output: Utf8PathBuf,	91	output: Utf8PathBuf,
92	},	92	},
93	/// Audit a corpus: report which org constructs it uses and how they land against	93	/// Audit a corpus: report which org constructs it uses and how each one lands.
94	/// the v1 scope line. Reports names, counts and locations — never document text.	94	/// Reports names, counts and locations — never document text.
95	Audit {	95	Audit {
96	/// Source directory (or single `.org` file) to audit.	96	/// Source directory (or single `.org` file) to audit.
97	input: Utf8PathBuf,	97	input: Utf8PathBuf,

src/parser.rs +16 −13

 //! PARSE is a pure function of a single file's bytes (spec §2.1): it never depends on
 //! another file, which is what makes content-hash caching sound.
 //!
-//! Scope is the v1 IN list (README §"v1 scope"): headings with nesting, TODO keywords,
+//! Scope is `docs/guide/05-org-support.org` §Supported: headings with nesting, TODO
-//! priorities, tags and property drawers; paragraphs; plain lists (unordered, ordered,
+//! keywords, priorities, tags and property drawers; paragraphs; plain lists (unordered,
-//! description) with checkboxes and nesting; tables; source/example/quote/center/export
+//! ordered, description) with checkboxes and nesting; tables; footnotes; `#+` keywords;
-//! blocks; footnotes; `#+` keywords; inline markup, links, timestamps; images with
+//! source, example, quote, center and export blocks; inline markup, links, timestamps;
-//! `#+CAPTION`/`#+ATTR_HTML`.
+//! images with `#+CAPTION`/`#+ATTR_HTML`.
 //!
-//! Out-of-scope constructs are parsed-and-ignored, never fatal: babel `:results` and
+//! A block name with no dedicated handling is a special block: a div carrying the name,
-//! `#+TBLFM:` are inert keywords, unknown block types keep their content verbatim as
+//! holding parsed org, which is what org's exporter emits for it.
-//! example blocks, generic drawers are captured and dropped at render, and LaTeX,
+//!
-//! macros and radio targets survive as literal text.
+//! Out-of-scope constructs are parsed-and-ignored, never fatal: babel `:results` is an
+//! inert keyword, generic drawers are captured and dropped at render, and LaTeX, macros
+//! and radio targets survive as literal text. `#+TBLFM:` is inert for the same reason
+//! org's exporter leaves it alone: it does not recalculate on export either.
 use camino::Utf8Path;
 use chrono::{NaiveDate, NaiveDateTime, NaiveTime};
         }
         if let Some((key, value)) = keyword_kv(line) {
             if key.eq_ignore_ascii_case("INCLUDE") {
-                // Never expanded (README §OUT). Expanding it means resolving paths,
+                // Never expanded (§"Not supported"). Expanding it means resolving paths,
                 // recursion and `:lines`/`:only-contents`; dropping it silently means a
                 // page missing content nobody was told about. Saying so is the honest
                 // middle, and `--strict` turns it into a failure.
                 });
             }
             if key.eq_ignore_ascii_case("RESULTS") {
-                // Babel is never executed (README §OUT), so a checked-in `#+RESULTS:`
+                // Babel is never executed (§"Not supported"), so a checked-in `#+RESULTS:`
                 // block is output from someone else's Emacs session at some other time.
                 // Emitting it would put unverifiable content on the page dressed as
                 // real content, so the block it labels is dropped.
 /// `:NAME:` … `:END:` at block level. A PROPERTIES drawer directly under a heading is
 /// consumed by [`parse_section_body`]; anything reaching here is a generic drawer,
-/// which the renderer drops (README §OUT).
+/// which the renderer drops (§"Not supported").
 fn parse_drawer(
     lines: &[&str],
     start: usize,
 /// One bracketed stamp → `(start, same-day end, has_time, index past the bracket)`.
 /// Day names (`Mon`) and repeater/warning cookies (`+1w`, `-2d`) are recognized and
-/// discarded — they carry no export meaning (README §OUT: agenda semantics).
+/// discarded — they carry no export meaning (§"Not supported": agenda semantics).
 fn parse_stamp(
     chars: &[char],
     i: usize,

src/render.rs +8 −7

 //!    and its cost must be cache-skippable (spec §4.2). Emit CSS classes, not inline
 //!    styles, so themes live in the stylesheet (spec §3.2).
 //!
-//! Renders the v1 IN set: headings (always anchored, with TODO keyword, priority and
+//! Renders the supported set (`docs/guide/05-org-support.org`): headings (always
-//! tags), paragraphs, plain lists (unordered/ordered/description, nested, with
+//! anchored, with TODO keyword, priority and tags), paragraphs, plain lists
-//! checkboxes), tables, source blocks (syntect-highlighted), example/quote/center
+//! (unordered/ordered/description, nested, with checkboxes), tables, source blocks
-//! blocks, HTML export blocks, horizontal rules, images and captioned figures,
+//! (syntect-highlighted), example/quote/center blocks, HTML export blocks, horizontal
-//! footnotes, timestamps, and inline markup. Out-of-scope elements (generic drawers,
+//! rules, images and captioned figures, footnotes, timestamps, and inline markup.
-//! comments, stray keywords, non-HTML export blocks) render to nothing.
+//! Out-of-scope elements (generic drawers, comments, stray keywords, non-HTML export
+//! blocks) render to nothing.
 use std::collections::HashMap;
 use std::sync::OnceLock;
                 out.push_str("</div>\n");
             }
             // An `html` export block is verbatim output by definition; every other
-            // backend is out of scope and drops (README §OUT).
+            // backend is out of scope and drops (§"Not supported").
             Element::ExportBlock { backend, raw } => {
                 if backend.eq_ignore_ascii_case("html") {
                     out.push_str(raw);

tests/constructs.rs +6 −6

tests/snapshots/constructs__out_of_scope_html.snap +1 −1

	@@ -2,7 +2,7 @@
2	source: tests/constructs.rs	2	source: tests/constructs.rs
3	expression: "render_fixture(\"outofscope.org\")"	3	expression: "render_fixture(\"outofscope.org\")"
4	---	4	---
5	<p>Every construct here is on the README's explicit OUT list. The contract is not that we handle them — it is that they degrade predictably and never crash the build.</p>	5	<p>Every construct here is on the explicit "Not supported" list in the org-support guide. The contract is not that we handle them — it is that they degrade predictably and never crash the build.</p>
6	<h2 id="babel">Babel</h2>	6	<h2 id="babel">Babel</h2>
7	<pre><code class="language-sh highlight"><span class="source shell bash"><span class="meta function-call shell"><span class="support function echo shell">echo</span></span><span class="meta function-call arguments shell"> <span class="string quoted double shell"><span class="punctuation definition string begin shell">"</span>the block renders; :results is never executed<span class="punctuation definition string end shell">"</span></span></span></span></code></pre>	7	<pre><code class="language-sh highlight"><span class="source shell bash"><span class="meta function-call shell"><span class="support function echo shell">echo</span></span><span class="meta function-call arguments shell"> <span class="string quoted double shell"><span class="punctuation definition string begin shell">"</span>the block renders; :results is never executed<span class="punctuation definition string end shell">"</span></span></span></span></code></pre>
8	<h2 id="table-formulas">Table formulas</h2>	8	<h2 id="table-formulas">Table formulas</h2>

	@@ -1,10 +1,10 @@
1	//! Golden-file coverage of the v1 scope line (README §"v1 scope").	1	//! Golden-file coverage of the scope line `docs/guide/05-org-support.org` draws.
2	//!	2	//!
3	//! Two halves, and the second is the point:	3	//! Two halves, and the second is the point:
4	//!	4	//!
5	//! - IN — every construct the v1 scope claims gets an element-tree snapshot (parser	5	//! - IN — every construct the guide claims gets an element-tree snapshot (parser
6	//! correctness) and a rendered-HTML snapshot (renderer correctness).	6	//! correctness) and a rendered-HTML snapshot (renderer correctness).
7	//! - OUT — every construct the v1 scope explicitly excludes gets an assertion that it	7	//! - OUT — every construct the guide explicitly excludes gets an assertion that it
8	//! degrades predictably: parsed and ignored, content preserved where that is the	8	//! degrades predictably: parsed and ignored, content preserved where that is the
9	//! honest fallback, never a crash and never a half-rendered artifact.	9	//! honest fallback, never a crash and never a half-rendered artifact.
10	//!	10	//!
	@@ -34,7 +34,7 @@ fn render_fixture(name: &str) -> String {
34	}	34	}
35		35
36	// ---------------------------------------------------------------------------	36	// ---------------------------------------------------------------------------
37	// IN: the constructs v1 promises to handle	37	// IN: the constructs the guide promises to handle
38	// ---------------------------------------------------------------------------	38	// ---------------------------------------------------------------------------
39		39
40	#[test]	40	#[test]
	@@ -180,7 +180,7 @@ fn unknown_source_language_falls_back_to_plain_code() {
180	}	180	}
181		181
182	// ---------------------------------------------------------------------------	182	// ---------------------------------------------------------------------------
183	// OUT: the constructs v1 explicitly excludes must degrade, not explode	183	// OUT: the constructs the guide explicitly excludes must degrade, not explode
184	// ---------------------------------------------------------------------------	184	// ---------------------------------------------------------------------------
185		185
186	/// The whole OUT fixture parses and renders. This is the crash gate.	186	/// The whole OUT fixture parses and renders. This is the crash gate.
	@@ -222,7 +222,7 @@ fn table_formulas_are_inert() {
222	);	222	);
223	}	223	}
224		224
225	/// LaTeX, macros and radio targets have no v1 semantics, so they survive as the literal	225	/// LaTeX, macros and radio targets have no orgo semantics, so they survive as the literal
226	/// text the author typed — lossless, and obviously unhandled to a reader.	226	/// text the author typed — lossless, and obviously unhandled to a reader.
227	#[test]	227	#[test]
228	fn latex_macros_and_radio_targets_stay_literal() {	228	fn latex_macros_and_radio_targets_stay_literal() {

Commit f274b51656

Commit `f274b51656`