7 files changed, 18 insertions, 104 deletions
diff --git a/custom/extensions/about-render.lua b/custom/extensions/about-render.lua
index 073b531..c4c1c93 100644
--- a/custom/extensions/about-render.lua
+++ b/custom/extensions/about-render.lua
@@ -66,8 +66,6 @@
 local ok_lpeg, lpeg = pcall(require, "lpeg")
 
 
--- ===== configuration ===================================================
-
 -- Readmes larger than this are served as escaped plain text rather than parsed.
 local max_bytes = 512 * 1024
 
@@ -78,8 +76,6 @@ local max_depth = 24
 local filename, chunks = "", {}
 
 
--- ===== helpers =========================================================
-
 local function trim(s)
 	return (s:gsub("^%s+", ""):gsub("%s+$", ""))
 end
@@ -135,7 +131,6 @@ local function safe_url(url)
 end
 
 
--- ===== emit ============================================================
 -- html, html_txt and html_attr are injected by cgit's lua filter host. Tag
 -- scaffolding is a literal argument to html; every value that came from the
 -- repository goes through html_txt, html_attr or safe_url.
@@ -226,8 +221,6 @@ emit_blocks = function(blocks)
 end
 
 
--- ===== plain text ======================================================
-
 local function render_plaintext(text)
 	html("<pre class='plaintext'>")
 	html_txt(text)
@@ -235,7 +228,6 @@ local function render_plaintext(text)
 end
 
 
--- ===== markdown and man ================================================
 -- Both are parsed with lpeg into the block/inline node trees emit_blocks and
 -- emit_inline above consume. Parsing is pure and builds a tree; emit is the
 -- only step that writes output, so a parse failure falls back to plain text
@@ -250,7 +242,6 @@ if ok_lpeg then
 	local ws = S(" \t\r\n\f\v")
 	local eol = P(-1)
 
-	-- ----- markdown inline -----
 	local marker = S("`![*_")
 	local urlchar = 1 - S(")") - ws
 	-- Bound the link and image inner scans. Without a cap a readme of unclosed
@@ -293,7 +284,6 @@ if ok_lpeg then
 		return nodes
 	end
 
-	-- ----- markdown blocks -----
 	-- Line matchers. Each is anchored at the start of a single line and returns
 	-- its captures, or nil when the line is not of that kind.
 	local langchar = R("az", "AZ", "09") + S("_.+#-")
@@ -415,7 +405,6 @@ if ok_lpeg then
 		html("</div>")
 	end
 
-	-- ----- man pages -----
 	-- Macro lines are matched with lpeg, and the roff inline font and character
 	-- escapes are an lpeg grammar producing a flat token list that a fold turns
 	-- into the same inline nodes markdown emits. Bold and italic are the current
@@ -560,8 +549,6 @@ else
 end
 
 
--- ===== dispatch ========================================================
-
 local handlers = {}
 for _, ext in ipairs({ "md", "markdown", "mkd", "mdown" }) do
 	handlers[ext] = render_markdown
diff --git a/custom/extensions/auth-file.lua b/custom/extensions/auth-file.lua
index 9c9c2ee..d003092 100644
--- a/custom/extensions/auth-file.lua
+++ b/custom/extensions/auth-file.lua
@@ -3,7 +3,7 @@
 --
 -- This is the FILE-BACKED variant. The user accounts, the groups, and the
 -- per-repository access lists are read from files on disk, whose paths are set
--- in the CONFIGURATION block below. Edit those files without touching this
+-- among the configuration values below. Edit those files without touching this
 -- script. This suits larger or externally managed user sets.
 --
 -- The companion auth-inline.lua behaves identically but keeps its accounts and
@@ -71,11 +71,8 @@ local unistd = require("posix.unistd")
 local rand = require("openssl.rand")
 local hmac = require("openssl.hmac")
 
---
--- ========================= CONFIGURATION =========================
--- Edit the values in this block. Nothing below it needs changing for
+-- Configuration, edit these values. Nothing below them needs changing for
 -- ordinary use.
---
 
 -- Accounts, one per line, as username:hash. Generate a hash with
 --     mkpasswd -m sha-512 -R 300000
@@ -110,10 +107,6 @@ local cookie_path = "/"
 -- HTTPS note in the header.
 local cookie_insecure = false
 
---
--- =================================================================
---
-
 -- A throwaway hash of the documented shape, used only to spend the same work
 -- on a missing account as on a present one, so a failed login does not reveal
 -- by timing whether the username exists.
@@ -122,12 +115,8 @@ local dummy_hash = "$6$rounds=300000$0000000000000000$"
 -- Module state shared across the open, write and close calls of one request.
 local action, http, cgit, post
 
---
---
 -- Account and access-list storage. This is the ONLY part that differs from
 -- auth-inline.lua. Swap these two functions to change where accounts live.
---
---
 
 local function trim(s)
 	return (string.gsub(s, "^%s*(.-)%s*$", "%1"))
@@ -203,11 +192,7 @@ function repo_userset(repo)
 	return users
 end
 
---
---
 -- Utility functions based on keplerproject/wsapi.
---
---
 
 function url_decode(str)
 	if not str then
@@ -265,11 +250,7 @@ function tohex(b)
 	return x
 end
 
---
---
 -- Cookie construction and validation helpers.
---
---
 
 local secret = nil
 
@@ -446,11 +427,7 @@ function not_found()
 	html("Cache-Control: no-cache, no-store\n\n")
 end
 
---
---
 -- Authentication actions. Identical to auth-inline.lua from here down.
---
---
 
 -- Sets HTTP cookie headers based on post and sets up redirection.
 function authenticate_post()
@@ -524,12 +501,8 @@ function body()
 	return 0
 end
 
---
---
 -- Wrapper around the filter API, exposing the http, cgit and post tables to
 -- the functions above.
---
---
 
 local actions = {}
 actions["authenticate-post"] = authenticate_post
diff --git a/custom/extensions/auth-inline.lua b/custom/extensions/auth-inline.lua
index 0cd9da9..faa3bdc 100644
--- a/custom/extensions/auth-inline.lua
+++ b/custom/extensions/auth-inline.lua
@@ -2,8 +2,8 @@
 -- session cookie.
 --
 -- This is the INLINE variant. The user accounts and the per-repository access
--- lists are written directly in this script, in the two tables in the
--- CONFIGURATION block below. Edit them here and reload. This suits a small
+-- lists are written directly in this script, in the two tables among the
+-- configuration values below. Edit them here and reload. This suits a small
 -- fixed set of users that rarely changes.
 --
 -- The companion auth-file.lua behaves identically but reads its accounts and
@@ -71,11 +71,8 @@ local unistd = require("posix.unistd")
 local rand = require("openssl.rand")
 local hmac = require("openssl.hmac")
 
---
--- ========================= CONFIGURATION =========================
--- Edit the values in this block. Nothing below it needs changing for
+-- Configuration, edit these values. Nothing below them needs changing for
 -- ordinary use.
---
 
 -- Protected repositories and the users allowed into each. A repository listed
 -- here is protected. One not listed is public. Keys and user names are matched
@@ -116,10 +113,6 @@ local cookie_path = "/"
 -- HTTPS note in the header.
 local cookie_insecure = false
 
---
--- =================================================================
---
-
 -- A throwaway hash of the documented shape, used only to spend the same work
 -- on a missing account as on a present one, so a failed login does not reveal
 -- by timing whether the username exists.
@@ -128,12 +121,8 @@ local dummy_hash = "$6$rounds=300000$0000000000000000$"
 -- Module state shared across the open, write and close calls of one request.
 local action, http, cgit, post
 
---
---
 -- Account and access-list storage. This is the ONLY part that differs from
 -- auth-file.lua. Swap these two functions to change where accounts live.
---
---
 
 -- Fold the configured tables to lowercased user names once, so lookups match
 -- case-insensitively the same way auth-file.lua does. Repository names keep
@@ -170,11 +159,7 @@ function repo_userset(repo)
 	return protected_repos[repo]
 end
 
---
---
 -- Utility functions based on keplerproject/wsapi.
---
---
 
 function url_decode(str)
 	if not str then
@@ -232,11 +217,7 @@ function tohex(b)
 	return x
 end
 
---
---
 -- Cookie construction and validation helpers.
---
---
 
 local secret = nil
 
@@ -413,11 +394,7 @@ function not_found()
 	html("Cache-Control: no-cache, no-store\n\n")
 end
 
---
---
 -- Authentication actions. Identical to auth-inline.lua from here down.
---
---
 
 -- Sets HTTP cookie headers based on post and sets up redirection.
 function authenticate_post()
@@ -491,12 +468,8 @@ function body()
 	return 0
 end
 
---
---
 -- Wrapper around the filter API, exposing the http, cgit and post tables to
 -- the functions above.
---
---
 
 local actions = {}
 actions["authenticate-post"] = authenticate_post
diff --git a/custom/extensions/email-gravatar.lua b/custom/extensions/email-gravatar.lua
index 47c359e..0e90031 100644
--- a/custom/extensions/email-gravatar.lua
+++ b/custom/extensions/email-gravatar.lua
@@ -36,9 +36,6 @@
 
 local digest = require("openssl.digest")
 
---
--- ===== CONFIGURATION =====
---
 
 -- Pixel size of the avatar.
 local avatar_size = 13
@@ -54,9 +51,6 @@ local base_url = "https://www.gravatar.com/avatar/"
 -- Text for the image alt attribute.
 local alt_text = "Gravatar"
 
---
--- =========================
---
 
 -- State shared across the open, write and close calls of one invocation.
 local buffer = ""
diff --git a/custom/extensions/email-libravatar.lua b/custom/extensions/email-libravatar.lua
index 812bef5..3538fe9 100644
--- a/custom/extensions/email-libravatar.lua
+++ b/custom/extensions/email-libravatar.lua
@@ -36,9 +36,6 @@
 
 local digest = require("openssl.digest")
 
---
--- ===== CONFIGURATION =====
---
 
 -- Pixel size of the avatar.
 local avatar_size = 13
@@ -53,9 +50,6 @@ local base_url = "https://seccdn.libravatar.org/avatar/"
 -- Text for the image alt attribute.
 local alt_text = "Libravatar"
 
---
--- =========================
---
 
 -- State shared across the open, write and close calls of one invocation.
 local buffer = ""
diff --git a/custom/extensions/link-commits.lua b/custom/extensions/link-commits.lua
index e7b17cc..fabd05b 100644
--- a/custom/extensions/link-commits.lua
+++ b/custom/extensions/link-commits.lua
@@ -10,12 +10,9 @@
 --
 -- Two kinds of thing are linked, object names (runs of hex that look like git
 -- hashes) and any number of text-reference rules you define, each a pattern
--- and a URL. Both are configured in the block below. All matches are resolved
+-- and a URL. Both are configured among the values below. All matches are resolved
 -- in a single left-to-right pass, so nothing is ever linked twice.
 
---
--- ===== CONFIGURATION =====
---
 
 -- Object names (git hashes). Handled specially, because the length rule cannot
 -- be written as a plain Lua pattern.
@@ -49,6 +46,11 @@ local objects = {
 -- {n,m} repetition. %d is a digit, %a a letter, %w a letter or digit, %x a hex
 -- digit, and a literal magic character is escaped with %, so a literal '-' is
 -- '%-'. Reference: https://www.lua.org/manual/5.1/manual.html#5.4.1
+--
+-- Patterns run against the escaped message, so '&', '<' and '>' reach them as
+-- '&amp;', '&lt;' and '&gt;'. Match those entity spellings rather than the
+-- bare character, and keep a pattern from ending part way through one, since
+-- the matched run is what gets wrapped in the anchor.
 local rules = {
 	{ pattern = "#(%d+)", url = "https://bugs.example.com/?bug=%s" },
 	-- { pattern = "CVE%-(%d%d%d%d%-%d+)", url = "https://www.cve.org/CVERecord?id=CVE-%s" },
@@ -56,9 +58,6 @@ local rules = {
 	-- { pattern = "RFC%s?(%d+)",          url = "https://www.rfc-editor.org/rfc/rfc%s" },
 }
 
---
--- =========================
---
 
 local chunks = {}
 
diff --git a/custom/extensions/syntax-highlight.lua b/custom/extensions/syntax-highlight.lua
index 8310504..b7ed822 100644
--- a/custom/extensions/syntax-highlight.lua
+++ b/custom/extensions/syntax-highlight.lua
@@ -9,10 +9,10 @@
 --
 -- SUPPORTED LUA
 --
--- Lua 5.1 through 5.4 and LuaJIT. The Scintillua version matters too. Recent
--- Scintillua (6.x) needs Lua 5.3 or newer to load its lexers, older Scintillua
--- releases still load under 5.1 and 5.2. Pick a Scintillua release that matches
--- the Lua cgit is built against.
+-- Lua 5.1 through 5.5 and LuaJIT. Scintillua 6.7 loads all of its lexers on
+-- LuaJIT, so the two do not have to be matched up. A lexer that will not load
+-- is skipped and that file falls back to plain escaped text, so a mismatched
+-- pair degrades rather than breaking the page.
 --
 -- REQUIREMENTS
 --
@@ -33,9 +33,9 @@
 --        # or with LuaRocks, matched to your Lua version
 --        sudo luarocks --lua-version 5.1 install lpeg
 --
--- 2. Scintillua, the lexer collection from the Textadept editor. Roughly 120
+-- 2. Scintillua, the lexer collection from the Textadept editor. Around 160
 --    languages as plain .lua files, nothing to compile. Download a release and
---    unpack it anywhere.
+--    unpack it anywhere. Only the lexers directory is needed.
 --
 --        https://orbitalquark.github.io/scintillua/
 --
@@ -43,7 +43,7 @@
 --
 --     $CGIT_SCINTILLUA_PATH        (used alone when set, no fallback)
 --     <dir of $CGIT_CONFIG>/scintillua/lexers
---     the scintillua_dirs list in the CONFIGURATION block below
+--     the scintillua_dirs list among the configuration values below
 --
 -- so either set the variable in the web server environment, or place (or
 -- symlink) the scintillua directory next to your cgitrc.
@@ -67,9 +67,6 @@
 -- assets/cgit.css styles. Every input byte up to the first NUL is preserved, so
 -- the line number gutter stays aligned.
 
---
--- ===== CONFIGURATION =====
---
 
 -- Files larger than this many bytes are served escaped but unhighlighted, so a
 -- huge blob does not cost a lexing pass. Kept well below cgit's max-blob-size.
@@ -120,9 +117,6 @@ local ext_lexer = {
 	rs = "rust", c = "ansi_c", h = "ansi_c",
 }
 
---
--- =========================
---
 
 local lexer_mod = nil
 local filename = ""