Upgrade 'make help' again

Makefile

@@ -23,16 +23,7 @@ MAKE_QUIETLY := MAKELEVEL= make
 
 .PHONY: all $(MAKECMDGOALS)
 
-help: # Show available Makefile targets
-	@echo "usage:"
-	@echo
-	@cat Makefile | \
-		grep -E '^[^.:[:space:]]+:|[#]##' | \
-		sed -E 's/:[^#]*#([^:]+)$$/: #:\1/' | \
-		sed -E 's/([^.:[:space:]]+):([^#]*#(.+))?.*/  make \1\3/' | \
-		sed -E 's/[#][#]# *(.+)/\n    (\1)\n/' | \
-		sed 's/$$/:/' | \
-		column -ts:
+ all: help
 
 ### Build packaging scripts
 
@@ -42,6 +33,9 @@ else
 NO_CACHE :=
 endif
 
+## Pass NC=1 to disable the Docker cache. Base images are not pulled;
+## see 'make pull-base' for that.
+
 image: # I=<image> [NC=1] : Build a Docker image
 	@: $${I}
 ifeq ($(I),composite)
@@ -62,7 +56,10 @@ scripts: # L=<lang> : Generate both lang and config packaging scripts
 	@: $${L}
 	node tools/make-foreach.js --types script L=$(L)
 
-all-scripts: # Generate all packaging scripts
+## This is equivalent to 'make script T=lang', 'make script T=config'.
+## For shared dependencies, use 'make script T=shared' directly.
+
+all-scripts: # Generate packaging scripts for all languages
 	node tools/write-all-build-scripts.js
 
 ### Run packaging scripts
@@ -82,12 +79,25 @@ pkg-debug: # L=<lang> T=<type> : Launch shell in packaging environment
 
 Z ?= none
 
+## Z is the compression type to use; defaults to none. Higher
+## compression levels (gzip is moderate, xz is high) take much longer
+## but produce much smaller packages.
+
 pkg-deb: # L=<lang> T=<type> [Z=gzip|xz] : Build .deb from packaging environment
 	@: $${L} $${T}
 	fakeroot dpkg-deb --build -Z$(Z) $(BUILD)/pkg $(BUILD)/$(DEB)
 
+## This is equivalent to the sequence 'pkg-clean', 'pkg-build', 'pkg-deb'.
+
 pkg: pkg-clean pkg-build pkg-deb # L=<lang> T=<type> [Z=gzip|xz] : Build fresh .deb
 
+## This is equivalent to 'make pkg T=lang', 'make pkg T=config'. For
+## shared dependencies, use 'make pkg T=shared' directly.
+#
+## Z is the compression type to use; defaults to none. Higher
+## compression levels (gzip is moderate, xz is high) take much longer
+## but produce much smaller packages.
+
 pkgs: # L=<lang> [Z=gzip|xz] : Build both lang and config .debs
 	@: $${L}
 	node tools/make-foreach.js --types pkg L=$(L)
@@ -130,11 +140,17 @@ else
 	docker run -it --rm --hostname $(I) -v $(VOLUME_MOUNT):/src $(SHELL_PORTS) $(SHELL_ENV) riju:$(I) $(BASH_CMD)
 endif
 
+## This is equivalent to 'make pkg' in a fresh packaging container
+## followed by 'make install' in a persistent runtime container.
+
 repkg: script # L=<lang> T=<type> : Build fresh .deb and install into live container
 	@: $${L} $${T}
 	$(MAKE_QUIETLY) shell I=packaging CMD="make pkg L=$(L) T=$(T)"
 	ctr="$$(docker container ls -f label="riju-install-target=yes" -l -q)"; test "$${ctr}" || (echo "no valid container is live"; exit 1); docker exec "$${ctr}" make install L=$(L) T=$(T)
 
+## This is equivalent to 'make repkg T=lang', 'make repkg T=config'.
+## For shared dependencies, use 'make repkg T=shared' directly.
+
 repkgs: # L=<lang> : Build and install fresh lang and config .debs
 	@: $${L}
 	node tools/make-foreach.js --types repkg L=$(L)
@@ -166,13 +182,25 @@ dev: # Compile, run, and watch all artifacts and server for development
 
 ### Application tools
 
+## L can be a language identifier or a test type (run, repl, lsp,
+## format, etc.). Multiple identifiers can be separated by spaces to
+## form a conjunction (AND), or by commas to form a disjunction (OR).
+
 test: # L=<filter> : Run test(s) for language or test category
 	node backend/test-runner.js $(L)
 
+## Functions such as 'repl', 'run', 'format', etc. are available in
+## the sandbox, and initial setup has already been done (e.g. 'setup'
+## command, template code written to main).
+
 sandbox: # L=<lang> : Run isolated shell with per-language setup
 	@: $${L}
 	L=$(L) node backend/sandbox.js
 
+## L can be either a language ID or a (quoted) custom command to start
+## the LSP. This does not run in a sandbox; the server is started
+## directly in the current working directory.
+
 lsp: # L=<lang|cmd> : Run LSP REPL for language or custom command line
 	@: $${C}
 	node backend/lsp-repl.js $(L)
@@ -211,17 +239,53 @@ upload: # L=<lang> T=<type> : Upload .deb to S3
 	aws s3 cp $(BUILD)/$(DEB) $(S3_DEB)
 	hash="$$(dpkg-deb -f $(BUILD)/$(DEB) Riju-Script-Hash | grep .)"; aws s3 cp - "$(S3_HASH)/$${hash}" < /dev/null
 
+## You should probably only run this from CI.
+
 publish: # Full synchronization and prod deployment
 	tools/publish.bash
 
 ### Miscellaneous
 
+## Run this every time you update .gitignore.
+
 dockerignore: # Update .dockerignore from .gitignore
 	echo "# This file is generated by 'make dockerignore', do not edit." > .dockerignore
 	cat .gitignore | sed 's#^#**/#' >> .dockerignore
 
+## You need to be inside a 'make env' shell whenever you are running
+## manual commands (Docker, Terraform, Packer, etc.) directly, as
+## opposed to through the Makefile.
+
 env: # Run shell with .env file loaded and $PATH fixed
 	exec bash --rcfile <(cat ~/.bashrc - <<< 'PS1="[.env] $$PS1"')
 
 tmux: # Start or attach to tmux session
 	MAKELEVEL= tmux attach || MAKELEVEL= tmux new-session -s tmux
+
+ usage:
+	@cat Makefile | \
+		grep -E '^[^.:[:space:]]+:|[#]##' | \
+		sed -E 's/:[^#]*#([^:]+)$$/: #:\1/' | \
+		sed -E 's/([^.:[:space:]]+):([^#]*#(.+))?.*/  make \1\3/' | \
+		sed -E 's/[#][#]# *(.+)/\n    (\1)\n/' | \
+		sed 's/$$/:/' | \
+		column -ts:
+
+help: # [CMD=<target>] : Show available targets, or detailed help for target
+ifeq ($(CMD),)
+	@echo "usage:"
+	@make -s usage
+	@echo
+else
+	@if ! make -s usage | grep -q "make $(CMD) "; then echo "no such target: $(CMD)"; exit 1; fi
+	@echo "usage:"
+	@make -s usage | grep "make $(CMD)"
+	@echo
+	@cat Makefile | \
+		grep -E '^[^.:[:space:]]+:|^##[^#]' | \
+		sed '/$(CMD):/Q' | \
+		tac | \
+		sed '/^[^#]/Q' | \
+		tac | \
+		sed -E 's/[# ]+//'
+endif