diff --git a/doc/i3-softdeps.test b/doc/i3-softdeps.test
new file mode 100644
index 0000000..d457d13
--- /dev/null
+++ b/doc/i3-softdeps.test
@@ -0,0 +1,279 @@
+Thanks to hestia and jaeger for inspiring this hacking session (2023-08-22).
+All commands were performed on a pkg-cleaned installation of CRUX 3.7, leaving
+the ports at whatever outdated version they had when this particular system was
+last in daily use.
+
+In light of the recent changes to libxkbcommon, jaeger made the observation
+that `prt-get depinst i3` on a core-only system hits an error, as
+libxkbcommon will be built without x11 support. To establish a reference point
+for subsequent experiments, here is the list of targets that would be selected
+by the latest official release of prt-get (5.19.6), in response to the
+recommended way of installing a desired port.
+
+In[0]: prt-get depinst --test i3
+Out[0]:
+*** prt-get: test mode
+
+-- Packages installed
+fribidi
+xorg-util-macros
+xorg-libpixman
+libev
+libpng
+libxml2
+xorg-xtrans
+libxkbcommon
+libxslt
+xorg-xcb-proto
+yajl
+xorg-xorgproto
+freetype
+glib
+xorg-libice
+xorg-libxau
+xorg-libxdmcp
+fontconfig
+gobject-introspection
+xorg-libsm
+xorg-libxcb
+xorg-libx11
+xorg-xcb-util
+xorg-xcb-util-renderutil
+xorg-xcb-util-keysyms
+xorg-xcb-util-wm
+xorg-libxext
+xorg-libxrender
+xorg-libxt
+xorg-libxkbfile
+xorg-xcb-util-image
+xorg-xcb-util-xrm
+cairo
+startup-notification
+xorg-xkbcomp
+xorg-xcb-util-cursor
+harfbuzz
+xkeyboard-config
+xorg-libxft
+pango
+i3
+
+-- installed packages with README files:
+fontconfig
+
+prt-get: installed successfully
+
+*** prt-get: test mode end
+
+As seen in the output above, at the time of building libxkbcommon, there are
+only 7 non-core ports installed, none of which is xkeyboard-config, 
+so the flag '-D enable-x11=false' gets passed to the meson setup command for
+libxkbcommon. Thus the necessary linking to x11 libs does not happen, and i3
+cannot compile successfully.
+
+Suppose we try to fix this omission in the most natural way: append
+xkeyboard-config at the end of i3's dependency list.
+
+ sed -i '/^# Depends on/s/$/ xkeyboard-config/' /usr/ports/opt/i3/Pkgfile
+
+Even this change is not enough! prt-get is not aware of the optional
+dependency relationship between libxkbcommon and xkeyboard-config, and so
+cannot insist that libxkbcommon comes later in the list of targets.
+
+Let's see whether farkuhar's softdeps-aware fork can do any better on this
+task. The naive approach, prt-get depinst --softdeps i3, still doesn't work
+because it will not automagically make two passes through the dependency tree
+(the first pass to assemble a minimal installation set, and the second pass to
+insert edges in the digraph based on optional dependency relationships among
+the targets found). Instead, you have to manually ask for two traversals of the
+dependency tree using a command substitution.
+
+In[1]: prt-get isinst $(prt-get quickdep i3) | awk '/not installed/ {print $2}' \
+    | xargs prt-get depinst --test --softdeps
+
+(Note that it's also necessary to filter out the already-installed ports before
+passing the quickdep output to `prt-get depinst` because this branch still
+makes a distinction between install and update transactions.)
+
+Out[1]:
+*** prt-get: test mode
+
+-- Packages installed
+fribidi
+xorg-util-macros
+xorg-libpixman
+libev
+xorg-xtrans
+libpng
+libxml2
+fontconfig
+libxslt
+xorg-xcb-proto
+yajl
+xorg-xorgproto
+glib [post: deferred]
+xorg-libxau
+xorg-libxdmcp
+xorg-libice
+xorg-libxcb
+xorg-libsm
+xorg-libx11
+xorg-xcb-util
+xorg-xcb-util-renderutil
+xorg-xcb-util-keysyms
+xorg-xcb-util-wm
+xorg-libxkbfile
+xorg-libxext
+xorg-libxrender
+xorg-libxt
+xorg-xcb-util-image
+xorg-xcb-util-xrm
+xorg-xkbcomp
+cairo
+startup-notification
+xorg-xcb-util-cursor
+xkeyboard-config
+gobject-introspection
+libxkbcommon
+harfbuzz
+freetype
+xorg-libxft
+pango
+i3
+
+-- installed packages with README files:
+/usr/ports/opt/fontconfig
+
+prt-get: installed successfully
+
+*** prt-get: test mode end
+
+
+This output looks more likely to succeed. Note that libxkbcommon would be built
+AFTER its optional dependency xkeyboard-config, because when xkeyboard-config
+appears among the depinst targets, that dependency relationship gets
+incorporated into the sorting algorithm.
+
+
+The mixed-upinst branch of farkuhar's prt-get goes further. Not only do you 
+get the feature of respecting optional dependencies, you can also do the 
+command substitution without the awk filter, and the appropriate mode 
+(install or update) will be selected for each target.
+
+In[2]: prt-get depinst --softdeps --test $(prt-get quickdep i3)
+
+Out[2]: 
+*** prt-get: test mode
+
+-- Successful packages 
+fribidi
+xz
+zlib
+ncurses
+expat
+libffi
+libnghttp2
+openssl
+libuv
+lzlib
+rhash
+xorg-util-macros
+libpcre2
+xorg-libpixman
+libev
+libpng
+elfutils
+libxml2
+readline
+fontconfig
+xorg-xtrans
+file
+curl
+libxslt
+sqlite3
+libarchive
+util-linux
+python3
+cmake
+python3-setuptools
+xorg-xcb-proto
+yajl
+meson
+xorg-xorgproto
+glib [post: deferred]
+xorg-libxau
+xorg-libxdmcp
+xorg-libice
+xorg-libxcb
+xorg-libsm
+xorg-libx11
+xorg-xcb-util
+xorg-xcb-util-renderutil
+xorg-xcb-util-keysyms
+xorg-xcb-util-wm
+xorg-libxkbfile
+xorg-libxext
+xorg-libxrender
+xorg-libxt
+xorg-xcb-util-image
+xorg-xcb-util-xrm
+xorg-xkbcomp
+cairo
+startup-notification
+xorg-xcb-util-cursor
+xkeyboard-config
+gobject-introspection
+libxkbcommon
+harfbuzz
+freetype
+xorg-libxft
+pango
+i3
+
+--  Successful packages with README files:
+fontconfig
+
+prt-get: install successful.
+
+*** prt-get: test mode end
+
+
+Remarks:
+1. The more intuitive version of the above commands, `prt-get depinst
+   --test --softdeps i3`, currently does NOT consider the dependency 
+   relationship "libxkbcommon optionally depends on xkeyboard-config", because
+   the latter port is neither currently installed, nor listed explicitly as an
+   install target. This safeguard is meant to allow the operation to proceed
+   after a SINGLE pass through the deptree, without pulling in ALL the ports
+   listed as "Optional:" . In future we might consider letting the more
+   intuitive command automatically make TWO passes through the deptree:
+   first to pick up all the hard dependencies, and then to insert edges in the
+   digraph that encode the optional dependencies among these targets. But such
+   "automagic side-effects" (two traversals versus one) are typically frowned
+   upon in CRUX, so for now we are happy to employ the command substitution
+   $(prt-get quickdep i3) thereby communicating to prt-get our intention for
+   two traversals of the deptree.
+
+
+2. The result of trial 2 would be identical to that of 
+   `prt-get install --softdeps $(prt-get quickdep i3)` using the 
+   mixed-upinst branch, because 'install' on this branch behaves the same
+   as 'depinst'. In https://lists.crux.nu/pipermail/crux/2008-June/001784.html
+   jw describes this change as "prt-get no more silently assumes that the user
+   didn't want a particular dependency".
+   farkuhar's mixed-upinst branch still gives you the option to override this
+   dependency-resolution-by-default; you just have to enter 'install --nodeps' 
+   instead of simply 'install'.
+
+
+3. Some maintainers prefer to do a filesystem check to determine whether a
+   needed dependency was linked to one of its optional libraries, and then
+   exit early with a message alerting the user to rebuild one of the packages
+   in the dependency tree. See contrib/libreoffice for an example. This
+   preference is arguably more aligned with CRUX's stance against excessively
+   "holding the user's hand". The softdeps feature is not intended to supplant
+   the user's thinking, but rather to give convenient access to a more versatile
+   topological sorting algorithm than the one coded in the official prt-get. The
+   toposort algorithm used in the above experiments remains true to the style
+   of jw's original code, but you can see another working implementation in
+   farkuhar's Perl rewrite
+   https://git.sdf.org/jmq/Documentation/src/branch/master/scripts/prt-auf .