Auto Man Page Update

man/man1/denv.1

@@ -148,6 +148,68 @@ image if it already exists
 include in tab-completions of denv.
 This is helpful if there are a set of common commands you use within the
 denv.
+.SH RUNNER DEDUCTION
+.PP
+denv does not persist what runner is being used inside of its
+configuration for a specific workspace.
+This is done intentionally so that configurations could be shared across
+machines that may rely on different runners; however, this could lead to
+confusion if denv is being used on a machine that has multiple runners
+installed.
+In this case, it is highly suggested to use
+\f[B]\f[CB]denv check\f[B]\f[R] and test-run the different runners to
+see which are capable of being used by denv.
+.IP
+.nf
+\f[C]
+# lists which runners it supports and which ones it has found
+denv check
+\f[R]
+.fi
+.PP
+A simple test would be to make sure denv can open a shell in some ubuntu
+image.
+Check different runners by using the environment variable
+\f[C]DENV_RUNNER\f[R].
+.IP
+.nf
+\f[C]
+denv init ubuntu:22.04
+# run this for each of the runners \[dq]found\[dq] by denv check
+DENV_RUNNER=<runner> denv
+\f[R]
+.fi
+.PP
+If any of the runners do not work (i.e.\ open an interactive bash
+terminal), please make a bug report by opening an issue for further
+investigation.
+However, there are some configurations of popular container runners that
+denv does not intend to support, so you may be forced to use a specific
+container runner out of the ones installed.
+In this case, it is highly recommended to define the
+\f[C]DENV_RUNNER\f[R] environment variable in your
+\f[C]\[ti]/.bashrc\f[R] (or equivalent) to avoid complication.
+.SS Automatic Deduction
+.PP
+denv does make some attempts to avoid this complexity by having an
+automatic choosing behavior that prefers runners that are more likely to
+be configured properly.
+For this reason, denv chooses to prefer runners that act as emulators
+over the runners they are emulating (for example, podman is checked
+before docker and apptainer is checked before singularity).
+In addition, since the configuration of podman on some computing
+clusters is not supportive of denv and apptainer is installed on these
+clusters, apptainer is checked before podman.
+This leads to the following order of priority currently within denv when
+\f[C]DENV_RUNNER\f[R] is not defined.
+.IP "1." 3
+apptainer
+.IP "2." 3
+singularity
+.IP "3." 3
+podman
+.IP "4." 3
+docker
 .SH FILES
 .PP
 This part of the manual is an attempt to list and explain the files