From c09020c2fb01da24d5befbed78ce3b73b5efbe4c Mon Sep 17 00:00:00 2001
From: Lukasz Kasprzak <lukas@labunix.xyz>
Date: Mon, 14 Sep 2026 23:39:37 +0200
Subject: content tests are three-valued: unknown when unreadable or read in
 part

---
 man/krino.1      | 11 +++++++++--
 man/krino.conf.5 | 24 ++++++++++++++++++++++--
 2 files changed, 31 insertions(+), 4 deletions(-)

(limited to 'man')

diff --git a/man/krino.1 b/man/krino.1
index 000fd95..2761048 100644
--- a/man/krino.1
+++ b/man/krino.1
@@ -193,8 +193,15 @@ checks every included directory.
 .It Ic explain Ar file
 Evaluate every exclusion and rule of
 .Ar file Ns 's
-directory against it and show each test's result, so a rule that should
-match but does not
+directory against it and show each test's result
+.Po
+.Ql yes ,
+.Ql no ,
+or
+.Ql \&?
+for a result that depends on content krino could not read
+.Pc ,
+so a rule that should match but does not
 .Pq or the reverse
 can be diagnosed test by test.
 See
diff --git a/man/krino.conf.5 b/man/krino.conf.5
index 26da541..c2df331 100644
--- a/man/krino.conf.5
+++ b/man/krino.conf.5
@@ -274,11 +274,14 @@ can test size and content.
 .Pp
 An
 .Ic exclude
-fails closed: when a content test it reaches cannot read the file
-.Pq over Ic max-read , No or a tool missing, failing or timing out ,
+fails closed: when its value depends on a content test that cannot read the
+file
+.Pq over Ic max-read , No a tool missing, failing or timing out, or a document read only in part ,
 the exclude holds and the file is set aside as
 .Dq (content unreadable) ,
 with a warning.
+An exclude that is false whatever the text holds does not
+.Pq see Sx Operators .
 A file whose format has no text at all, such as an image or an archive,
 is not unreadable: its content tests are false, with no warning.
 So is a file of no known extension that starts as text and holds binary
@@ -365,6 +368,23 @@ and
 take one or more arguments;
 .Ic not
 exactly one.
+.Pp
+A
+.Ic content
+test that cannot read its file is unknown, with a warning; a document read
+only in part answers the keywords found in what was read and leaves the
+others unknown.
+Operators combine unknowns by three-valued logic:
+.Ic and
+is false if any argument is false,
+.Ic or
+true if any is true, and
+.Ic not
+of unknown is unknown.
+A rule matches only when its condition is true, so
+.Ql (not (content \(dqx\(dq))
+never acts on a file krino could not read; an exclusion holds when its
+condition is true or unknown.
 .Ss Tests
 .Bl -tag -width Ds
 .It Ic (type Ar t No ...)
-- 
cgit v1.3