Restyle the sources and fix the audit's findings

1 file changed, 34 insertions, 31 deletions

diff --git a/Makefile b/Makefile
index 010427b..e4ff38a 100644
--- a/Makefile
+++ b/Makefile
@@ -1,13 +1,17 @@
-# cgit top-level Makefile. cgit itself is compiled inside the bundled Git tree
-# by source/cgit.mk, which this file invokes; everything else (docs, install,
-# packaging, maintenance) is driven from here.
+# The entry point for building, documenting and installing cgit. The program
+# itself is compiled inside the bundled Git tree by source/cgit.mk, which this
+# file invokes with the paths and the defaults it needs. Everything that is not
+# compilation, that is the manual page, the install and uninstall rules and the
+# housekeeping targets, is driven from here.
 
 .DEFAULT_GOAL := all
 .SUFFIXES:
 
-# Project layout. Sources live in source/, web assets in assets/, Lua filters
-# in custom/extensions/, the bundled Git tree in vendor/git, and every generated
-# file lands in build/. CGIT_ROOT reaches from the Git tree back to the root.
+# Sources live in source/, web assets in assets/, Lua filters in
+# custom/extensions/, the bundled Git tree in vendor/git, and everything
+# generated lands in build/. CGIT_ROOT leads from inside the Git tree back to
+# the project root, because the cgit build runs with vendor/git as its working
+# directory.
 SRCDIR   = source
 ASSETDIR = assets
 EXTDIR   = custom/extensions
@@ -15,13 +19,14 @@ GITDIR   = vendor/git
 BUILDDIR = build
 CGIT_ROOT = ../..
 
-# Git release fetched by get-git when the submodule is not checked out. Keep in
-# step with the submodule pin in .gitmodules.
+# The Git release that get-git fetches when the submodule is not checked out.
+# Keep it in step with the submodule pin in .gitmodules.
 GIT_VERSION = 2.55.0
 GIT_URL = https://www.kernel.org/pub/software/scm/git/git-$(GIT_VERSION).tar.xz
 
-# Compiled-in cgit defaults, overridable through cgit.conf. All carry the CGIT_
-# prefix except CACHE_ROOT, inherited from upstream under that name.
+# Compiled-in cgit defaults, all overridable through cgit.conf. Every one
+# carries the CGIT_ prefix except CACHE_ROOT, which is inherited from upstream
+# under that name.
 CGIT_VERSION = v2.2.0
 CGIT_SCRIPT_NAME = cgit.cgi
 CGIT_SCRIPT_PATH = /var/www/htdocs/cgit
@@ -29,8 +34,8 @@ CGIT_DATA_PATH = $(CGIT_SCRIPT_PATH)
 CGIT_CONFIG = /etc/cgitrc
 CACHE_ROOT = /var/cache/cgit
 
-# Standard GNU-style install directories, lowercase so packaging can override
-# them; filterdir is the one cgit-specific addition.
+# The standard GNU install directories, kept lowercase so that packaging can
+# override them. filterdir is the one cgit-specific addition.
 prefix = /usr/local
 libdir = $(prefix)/lib
 filterdir = $(libdir)/cgit/filters
@@ -38,13 +43,14 @@ docdir = $(prefix)/share/doc/cgit
 htmldir = $(docdir)
 mandir = $(prefix)/share/man
 
-# Files installed into the data path and the filter dir. One list each drives
-# both install and uninstall, so the two can never drift apart.
+# The files that go into the data path and the filter directory. One list each
+# drives both install and uninstall, so the two can never drift apart.
 ASSETS       = cgit.css cgit.js cgit.png favicon.ico robots.txt
 FILTER_FILES = $(notdir $(wildcard $(EXTDIR)/*.lua))
 
-# The man-page source (*.5.txt) sits at the project root and is rendered into
-# build/. Only one man section exists, so DOC_* derive straight from MAN5_TXT.
+# The manual page source, *.5.txt, sits at the project root and is rendered
+# into build/. Only one man section exists, so both document lists derive
+# straight from MAN5_TXT.
 MAN5_TXT = $(wildcard *.5.txt)
 DOC_MAN5 = $(patsubst %.txt,$(BUILDDIR)/%,$(MAN5_TXT))
 DOC_HTML = $(patsubst %.txt,$(BUILDDIR)/%.html,$(MAN5_TXT))
@@ -56,8 +62,8 @@ ASCIIDOC_HTML = xhtml11
 ASCIIDOC_COMMON = $(ASCIIDOC) $(ASCIIDOC_EXTRA)
 TXT_TO_HTML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_HTML)
 
-# Reuse Git's platform detection, then let the user override any of the settings
-# above through cgit.conf. Both includes must stay after the defaults.
+# Reuse Git's platform detection, then let the user override any of the
+# settings above through cgit.conf. Both includes must stay after the defaults.
 -include $(GITDIR)/config.mak.uname
 -include cgit.conf
 
@@ -65,13 +71,10 @@ export CGIT_VERSION CGIT_SCRIPT_NAME CGIT_SCRIPT_PATH CGIT_DATA_PATH CGIT_CONFIG
 
 all: cgit
 
-# cgit is compiled inside the bundled Git tree so it can reuse Git's build
-# machinery (see source/cgit.mk). Objects and the binary go to build/.
-#
-# NO_RUST keeps Cargo out of the build. Git 2.55 inverted the flag that used
-# to be WITH_RUST, so Rust is now compiled in unless it is turned off, and
-# leaving this out would quietly make Cargo a build requirement. Git 3.0 drops
-# the choice entirely, at which point this stops working and Rust becomes
+# NO_RUST keeps Cargo out of the build. Git 2.55 inverted the flag that used to
+# be WITH_RUST, so Rust is now compiled in unless it is turned off, and leaving
+# this out would quietly make Cargo a build requirement. Git 3.0 drops the
+# choice entirely, at which point this stops working and Rust becomes
 # mandatory.
 GIT_BUILD_FLAGS = NO_CURL=1 NO_OPENSSL=1 NO_RUST=1
 
@@ -86,8 +89,8 @@ sparse:
 test: cgit-with-git
 	+@$(MAKE) -C tests all
 
-# The test helpers link against a fully built Git tree, so this asks the
-# sub-make for Git's own `all` alongside cgit.
+# The test helpers link against a fully built Git tree, so this asks the sub
+# make for Git's own all target alongside cgit.
 cgit-with-git:
 	+@$(MAKE) cgit EXTRA_GIT_TARGETS=all
 
@@ -138,9 +141,10 @@ uninstall-html:
 	    rm -fv $(DESTDIR)$(htmldir)/$$i; \
 	done
 
-# Compiled output lives under build/; the test suite writes into tests/, so
-# cleaning removes both. The tests descent is guarded because tests/Makefile
-# includes git's config.mak.uname, which needs the submodule present.
+# Compiled output lives under build/ and the test suite writes into tests/, so
+# cleaning removes both. The descent into tests is guarded because
+# tests/Makefile includes git's config.mak.uname, which needs the submodule
+# present.
 clean:
 	$(RM) -r $(BUILDDIR)
 	@if test -e $(GITDIR)/config.mak.uname; then $(MAKE) -C tests clean; fi
@@ -148,7 +152,6 @@ clean:
 cleanall: clean
 	@if test -e $(GITDIR)/Makefile; then $(MAKE) -C $(GITDIR) clean; fi
 
-# Fetch a Git release tarball for builds without the submodule checked out.
 get-git:
 	mkdir -p $(dir $(GITDIR))
 	curl -L $(GIT_URL) | tar -xJf - && rm -rf $(GITDIR) && mv git-$(GIT_VERSION) $(GITDIR)