From 2cc31a1381547c31bf202e3e1613915062c428b3 Mon Sep 17 00:00:00 2001 From: Amr Gharbeia Date: Wed, 13 May 2026 13:17:08 -0400 Subject: [PATCH] docs: document check-parens limitation with multi-block forms Some literate files split a single form across multiple blocks. check-parens checks per-block, so these produce false positives. Recommend check-tangle as an alternative for those files. --- projects/check-parens/README.org | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/projects/check-parens/README.org b/projects/check-parens/README.org index db01508..3e0e151 100644 --- a/projects/check-parens/README.org +++ b/projects/check-parens/README.org @@ -3,8 +3,20 @@ Standalone parentheseis checker for Lisp source blocks in Org files. -Scans all ~#+begin_src lisp … #+end_src~ blocks in an Org file, strips -string and comment content, and reports unbalanced parentheses per block. +Scans all ~#+begin_src lisp … #+end_src~ blocks in an Org file, uses +SBCL's reader to validate each block. 100% accurate — no false positives +from string literals or character literals (e.g. ~#\)~). + +== Limitations + +Each ~#+begin_src lisp~ block is checked independently. Some literate +files intentionally split a single form (e.g. a ~defpackage~ with many +symbols) across multiple blocks with prose between them. In such cases +no individual block is self-contained and check-parens will report +false positives. + +To verify these files, tangle and compile the resulting .lisp instead: + check-tangle == Usage