diff --git a/Makefile b/Makefile
index f2ae6d752b..d321517f96 100644
--- a/Makefile
+++ b/Makefile
@@ -469,6 +469,11 @@ $(MANPAGES): %: %.md .install.md2man docdir
 	       -e 's;<\(/\)\?\(a\|a\s\+[^>]*\|sup\)>;;g'    \
 	       -e 's/\\$$/  /g' $<                         |\
 	$(GOMD2MAN) -out $(subst source/markdown,build/man,$@)
+# FIXME: 2023-02-16: we may need a multi-commit approach to
+# enable this.
+#	@if grep 'included file options/' docs/build/man/*; then \
+#		echo "FATAL: man pages must not contain ^^^^"; exit 1; \
+#	fi
 
 .PHONY: docdir
 docdir:
diff --git a/docs/source/markdown/options/secret.md b/docs/source/markdown/options/secret.md
index cd9a6a6e9d..e81abfb679 100644
--- a/docs/source/markdown/options/secret.md
+++ b/docs/source/markdown/options/secret.md
@@ -36,11 +36,17 @@ Secret Options
 
 Examples
 
-Mount at `/my/location/mysecret` with UID 1.
-```--secret mysecret,target=/my/location/mysecret,uid=1```
+Mount at `/my/location/mysecret` with UID 1:
+```
+--secret mysecret,target=/my/location/mysecret,uid=1
+```
 
-Mount at `/run/secrets/customtarget` with mode 0777.
-```--secret mysecret,target=customtarget,mode=0777```
+Mount at `/run/secrets/customtarget` with mode 0777:
+```
+--secret mysecret,target=customtarget,mode=0777
+```
 
-Create a secret environment variable called `ENVSEC`.
-```--secret mysecret,type=env,target=ENVSEC```
+Create a secret environment variable called `ENVSEC`:
+```
+--secret mysecret,type=env,target=ENVSEC
+```