upload results of the i3 softdeps test

doc/i3-softdeps.test

@@ -0,0 +1,204 @@
+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.
+
+
+First let's change the i3 Pkgfile to append xkeyboard-config at the end of the
+dependency list.
+
+In[0]: sed -i '/^# Depends on/s/$/ xkeyboard-config/' /usr/ports/opt/i3/Pkgfile
+
+
+On the softdeps branch of farkuhar's prt-get, you have 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.
+
+In[1]: prt-get isinst $(prt-get quickdep i3) | awk '/not installed/ {print $2}' \
+    | xargs prt-get depinst --test --softdeps
+
+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
+
+
+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 build up the sorted list with 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 .