diff --git a/doc/foot.1.scd b/doc/foot.1.scd
index 52ccebd1..6f0ad6db 100644
--- a/doc/foot.1.scd
+++ b/doc/foot.1.scd
@@ -458,7 +458,7 @@ In all other cases, the exit code is that of the client application
 
 # ENVIRONMENT
 
-The following environment variables are used by foot:
+## Variables used by foot
 
 *SHELL*
 	The default child process to run, when no _command_ argument is
@@ -492,7 +492,7 @@ The following environment variables are used by foot:
 	The size to use for *Xcursor*(3) pointers (typically set by the
 	Wayland compositor).
 
-The following environment variables are set in the child process:
+## Variables set in the child process
 
 *TERM*
 	terminfo/termcap identifier. This is used by client applications
@@ -504,6 +504,9 @@ The following environment variables are set in the child process:
 	This variable is set to *truecolor*, to indicate to client
 	applications that 24-bit RGB colors are supported.
 
+In addition to the variables listed above, custom environment
+variables may be defined in *foot.ini*(5).
+
 # BUGS
 
 Please report bugs to https://codeberg.org/dnkl/foot/issues
diff --git a/doc/foot.ini.5.scd b/doc/foot.ini.5.scd
index 9c7ccf29..bc1b6bdd 100644
--- a/doc/foot.ini.5.scd
+++ b/doc/foot.ini.5.scd
@@ -305,6 +305,19 @@ commented out will usually be installed to */etc/xdg/foot/foot.ini*.
 	(including SMT). Note that this is not always the best value. In
 	some cases, the number of physical _cores_ is better.
 
+# SECTION: environment
+
+This section is used to define environment variables that will be set
+in the client application, in addition to the variables inherited from
+the terminal process itself.
+
+The format is simply:
+
+*name*=_value_
+
+Note: do not set *TERM* here; use the *term* option in the main
+(default) section instead.
+
 # SECTION: bell
 
 *urgent*
diff --git a/doc/footclient.1.scd b/doc/footclient.1.scd
index 285ff184..967a4f1b 100644
--- a/doc/footclient.1.scd
+++ b/doc/footclient.1.scd
@@ -136,7 +136,7 @@ terminfo entries manually, by copying *foot* and *foot-direct* to
 
 # ENVIRONMENT
 
-The following environment variables are used by footclient:
+## Variables used by footclient
 
 *XDG\_RUNTIME\_DIR*
 	Used to construct the default _PATH_ for the *--server-socket*
@@ -146,7 +146,7 @@ The following environment variables are used by footclient:
 	Used to construct the default _PATH_ for the *--server-socket*
 	option, when no explicit argument is given (see above).
 
-The following environment variables are set in the child process:
+## Variables set in the child process
 
 *TERM*
 	terminfo/termcap identifier. This is used by client applications
@@ -158,6 +158,9 @@ The following environment variables are set in the child process:
 	This variable is set to *truecolor*, to indicate to client
 	applications that 24-bit RGB colors are supported.
 
+In addition to the variables listed above, custom environment
+variables may be defined in *foot.ini*(5).
+
 # SEE ALSO
 
 *foot*(1)