1 file changed, 49 insertions, 48 deletions
diff --git a/custom/extensions/email-gravatar.lua b/custom/extensions/email-gravatar.lua
index 0e90031..6ce688f 100644
--- a/custom/extensions/email-gravatar.lua
+++ b/custom/extensions/email-gravatar.lua
@@ -1,17 +1,18 @@
--- cgit email-filter that shows a Gravatar icon next to author names. Use it
--- with the email-filter or repo.email-filter setting and the lua: prefix.
+-- cgit email-filter that puts a Gravatar icon next to an author name. Enable
+-- it with the email-filter or repo.email-filter setting and the lua: prefix,
+-- so it runs in cgit's embedded interpreter with no per-request process. The
+-- companion email-libravatar.lua is the same filter pointed at Libravatar
+-- instead.
 --
 --     email-filter=lua:/path/to/email-gravatar.lua
 --
--- SUPPORTED LUA
+-- Runs on Lua 5.1, 5.2, 5.3, 5.4 and LuaJIT. Lua 5.5 is not supported, because
+-- luaossl has no 5.5 build.
 --
--- Lua 5.1, 5.2, 5.3, 5.4 and LuaJIT. Lua 5.5 is not supported, because luaossl
--- has no 5.5 build.
---
--- DEPENDENCY
---
---     luaossl    OpenSSL binding, provides openssl.digest
---                <https://github.com/wahern/luaossl>
+-- The one dependency is luaossl, the OpenSSL binding that provides
+-- openssl.digest, from <https://github.com/wahern/luaossl>. The reliable
+-- cross-platform install is LuaRocks, matched to the Lua version cgit is built
+-- against, and it needs the OpenSSL development headers present.
 --
 --     # Debian and Ubuntu
 --     sudo apt install luarocks libssl-dev
@@ -25,49 +26,46 @@
 --     brew install luarocks openssl
 --     luarocks install luaossl OPENSSL_DIR="$(brew --prefix openssl)"
 --
--- PRIVACY
---
 -- Every page view sends the visitor's IP address and a hash of each
--- committer's email to a third-party service. Leave this filter off if that is
--- not acceptable for your instance.
---
--- Addresses are hashed with MD5, which Gravatar still accepts. Gravatar also
--- supports SHA-256 now, change the digest in hash_hex if you prefer it.
+-- committer's email to a third-party service, so leave this filter off if that
+-- is not acceptable for your instance. Addresses are hashed with MD5, which
+-- Gravatar still accepts. Gravatar also supports SHA-256 now, so change the
+-- digest in hash_hex if you prefer it.
 
 local digest = require("openssl.digest")
 
 
--- Pixel size of the avatar.
+-- These are the values to change. The size is in pixels and serves both as the
+-- image asked of the service and as the width and height attributes. The
+-- default image is the style Gravatar draws for an address it has never seen,
+-- and its documented choices include retro, identicon, monsterid and mp. The
+-- endpoint is https so the icon is not blocked as mixed content on an https
+-- page.
 local avatar_size = 13
-
--- Fallback style for an address with no avatar. See the Gravatar docs for the
--- choices, for example retro, identicon, monsterid or mp.
 local default_image = "retro"
-
--- Avatar endpoint. Kept https so the image is not blocked as mixed content on
--- an https page.
 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.
+-- cgit calls filter_open once, then filter_write for each piece of the name,
+-- then filter_close, so what one call works out has to be left here for the
+-- next one.
 local buffer = ""
-local avatar = nil
+local avatar_hash = nil
 
 local function hash_hex(input)
-	local b = digest.new("md5"):final(input)
-	local x = ""
-	for i = 1, #b do
-		x = x .. string.format("%.2x", string.byte(b, i))
+	local raw = digest.new("md5"):final(input)
+	local hex = ""
+	for i = 1, #raw do
+		hex = hex .. string.format("%.2x", string.byte(raw, i))
 	end
-	return x
+	return hex
 end
 
--- Take the address, strip the angle brackets if present, then trim and
--- lowercase as the avatar services expect. Returns nil for a missing or empty
--- address.
+-- cgit can hand over the address still wrapped in angle brackets, and the
+-- service hashes the trimmed lowercase form, so an address that skipped this
+-- would hash to something the service has never heard of. A missing or empty
+-- address becomes nil, which is how the caller knows to draw no icon.
 local function normalize_email(email)
 	if email == nil then
 		return nil
@@ -85,25 +83,28 @@ end
 
 function filter_open(email, page)
 	buffer = ""
-	local addr = normalize_email(email)
-	if addr == nil then
-		avatar = nil
+	local address = normalize_email(email)
+	if address == nil then
+		avatar_hash = nil
 	else
-		avatar = hash_hex(addr)
+		avatar_hash = hash_hex(address)
 	end
 end
 
+function filter_write(text)
+	buffer = buffer .. text
+end
+
 function filter_close()
-	if avatar == nil then
-		-- No usable address, render the name without an icon.
+	if avatar_hash == nil then
 		html(buffer)
 	else
-		html("<img src='" .. base_url .. avatar .. "?s=" .. avatar_size .. "&amp;d=" .. default_image ..
-			"' width='" .. avatar_size .. "' height='" .. avatar_size .. "' alt='" .. alt_text .. "' /> " .. buffer)
+		html("<img src='" .. base_url .. avatar_hash ..
+			"?s=" .. avatar_size ..
+			"&amp;d=" .. default_image ..
+			"' width='" .. avatar_size ..
+			"' height='" .. avatar_size ..
+			"' alt='" .. alt_text .. "' /> " .. buffer)
 	end
 	return 0
 end
-
-function filter_write(str)
-	buffer = buffer .. str
-end