guide/09-auditing.html
91 lines · 8654 bytes
1<!DOCTYPE html>
2<html lang="en">
3<head>
4<meta charset="utf-8">
5<meta name="viewport" content="width=device-width, initial-scale=1">
6<title>Auditing a corpus · orgo</title>
7<meta name="description" content="Find out what a tool will make of your writing before you trust it with it.">
8<link rel="icon" href="../favicon.svg" type="image/svg+xml">
9<link rel="stylesheet" href="../theme.css">
10<link rel="stylesheet" href="../syntax.css">
11<link rel="stylesheet" href="../style.css">
12</head>
13<body>
14<header class="site">
15<a class="site-title" href="../index.html">orgo</a>
16<nav>
17<a href="../install.html">Install</a>
18<a href="../quickstart.html">Quick start</a>
19<a href="index.html">Guide</a>
20</nav>
21</header>
22<main>
23<h1>Auditing a corpus</h1>
24<p class="lede">Construct frequencies, unknown-name census, and no document text in the output.</p>
25<nav class="toc" aria-label="On this page">
26<h2>On this page</h2>
27<ul>
28<li><a href="#reading-the-output">Reading the output</a></li>
29<li><a href="#it-never-prints-your-writing">It never prints your writing</a></li>
30<li><a href="#why-it-is-a-separate-scanner">Why it is a separate scanner</a></li>
31<li><a href="#comparing-against-emacs">Comparing against Emacs</a></li>
32<li><a href="#using-the-audit-before-a-migration">Using the audit before a migration</a></li>
33</ul>
34</nav>
35<pre><code class="language-sh highlight"><span class="source shell bash"><span class="meta function-call shell"><span class="variable function shell">orgo</span></span><span class="meta function-call arguments shell"> audit <span class="meta group expansion tilde"><span class="variable language tilde shell">~</span></span>/notes</span></span></code></pre>
36<p>The audit answers two questions about a body of org files:</p>
37<ol>
38<li><strong>Coverage.</strong> Of the constructs this corpus uses, which are supported? A construct that is common here and unsupported is a problem with the tool's scope, not with your writing.</li>
39<li><strong>Blind spots.</strong> Which names appear that orgo has no opinion about at all? These are the dangerous ones — not "known unsupported" but unknown.</li>
40</ol>
41<h2 id="reading-the-output">Reading the output</h2>
42<pre>corpus: 180 file(s), 29742 line(s)
43
44CONSTRUCTS (by frequency)
45 construct uses files first seen
46IN list item 1309 111 blog/2018-11-28-aes-encryption.org:53
47IN heading 1148 176 blog/2018-11-28-aes-encryption.org:7
48IN verbatim 1048 130 blog/2018-11-28-aes-encryption.org:79
49...
50IN table formula (#+TBLFM:) 4 1 blog/2024-08-11-org-mode-features.org:191
51IN special block 1 1 blog/2026-03-03-auditing-aws-s3.org:50
52
53coverage: 9002 in-scope use(s) (100.0%), 0 out-of-scope (0.0%)
54
55KEYWORDS
56 SLUG 180 180 blog/2018-11-28-aes-encryption.org:4
57 TITLE 180 180 blog/2018-11-28-aes-encryption.org:2
58— LEDE 14 14 blog/2018-11-28-aes-encryption.org:3
59...</pre>
60<ul>
61<li><code class="verbatim">IN</code> is supported; <code class="verbatim">OUT</code> is excluded by design and degrades as described in <a href="05-org-support.html">Org support</a>.</li>
62<li>The <strong>coverage</strong> line is the number to look at first.</li>
63<li><code class="verbatim">???</code> 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. Keyword names never carry it either — see below.</li>
64<li><code class="verbatim">—</code> marks a keyword with no dedicated handling. It is not a gap: the keyword reaches your layout as <code class="verbatim">{{ page.keywords.<name> }}</code>, 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.</li>
65</ul>
66<p>Four censuses follow the construct table: every distinct <code class="verbatim">#+KEYWORD:</code>, block type, drawer name and link scheme in the corpus. A <code class="verbatim">???</code> in any of them is worth a look.</p>
67<h2 id="it-never-prints-your-writing">It never prints your writing</h2>
68<p>Names, counts and <code class="verbatim">file:line</code> locations only. That is a deliberate constraint so that an audit of private notes — work notes, a journal — is safe to paste into an issue or share with someone helping you.</p>
69<h2 id="why-it-is-a-separate-scanner">Why it is a separate scanner</h2>
70<p>The audit deliberately does <strong>not</strong> reuse the parser. Auditing with the parser could only ever find constructs the parser already knows about, which is exactly the wrong instrument for the second question: it would report a blind spot as clean.</p>
71<h2 id="comparing-against-emacs">Comparing against Emacs</h2>
72<p>The second half of the same idea is a differential test suite. <code class="verbatim">cargo test --test oracle</code> exports each fixture with org's own HTML exporter through <code class="verbatim">emacs --batch</code>, reduces both outputs to a semantic skeleton, and <strong>snapshots the disagreement</strong>.</p>
73<pre><code class="language-sh highlight"><span class="source shell bash"><span class="meta function-call shell"><span class="variable function shell">cargo</span></span><span class="meta function-call arguments shell"> test<span class="variable parameter option shell"><span class="punctuation definition parameter shell"> --</span>test</span> oracle</span></span></code></pre>
74<p>Snapshotting rather than asserting agreement is deliberate: a checked-in divergence report gets reviewed and shows up in code review, where a permanently red test gets ignored. Three invariants <em>are</em> asserted outright — heading structure, list nesting and source-block text — and all three hold.</p>
75<p>The suite skips cleanly with no Emacs installed, so a machine without it still gets a green run; it simply measures one thing less.</p>
76<h2 id="using-the-audit-before-a-migration">Using the audit before a migration</h2>
77<pre><code class="language-sh highlight"><span class="source shell bash"><span class="comment line number-sign shell"><span class="punctuation definition comment begin shell">#</span></span><span class="comment line number-sign shell"> What is in there?</span><span class="comment line number-sign shell">
78</span><span class="meta function-call shell"><span class="variable function shell">orgo</span></span><span class="meta function-call arguments shell"> audit <span class="meta group expansion tilde"><span class="variable language tilde shell">~</span></span>/notes</span>
79
80<span class="comment line number-sign shell"><span class="punctuation definition comment begin shell">#</span></span><span class="comment line number-sign shell"> Build it and see what the builder itself complains about.</span><span class="comment line number-sign shell">
81</span><span class="meta function-call shell"><span class="variable function shell">orgo</span></span><span class="meta function-call arguments shell"> build <span class="meta group expansion tilde"><span class="variable language tilde shell">~</span></span>/notes<span class="variable parameter option shell"><span class="punctuation definition parameter shell"> -</span>o</span> /tmp/preview<span class="variable parameter option shell"><span class="punctuation definition parameter shell"> --</span>strict</span></span>
82
83<span class="comment line number-sign shell"><span class="punctuation definition comment begin shell">#</span></span><span class="comment line number-sign shell"> Look at the result.</span><span class="comment line number-sign shell">
84</span><span class="meta function-call shell"><span class="variable function shell">orgo</span></span><span class="meta function-call arguments shell"> serve <span class="meta group expansion tilde"><span class="variable language tilde shell">~</span></span>/notes<span class="variable parameter option shell"><span class="punctuation definition parameter shell"> -</span>o</span> /tmp/preview</span></span></code></pre>
85<p><code class="verbatim">--strict</code> surfaces broken internal links and malformed constructs as failures rather than warnings, which is the fastest way to find the handful of files that need attention before you commit to anything.</p>
86</main>
87<footer class="site">
88Built with orgo — these docs are an orgo site.
89</footer>
90</body>
91</html>