4. XBPS Package Manager documentation is deadlocked

I collected some examples and arguments, and old issues like #616, to show how much could be won be harmonizing the XBPS pages at 4. and 4.1 with the rest and the man pages. In total accordance with 1.2 About This Handbook

purpose of this document is to explain how to install, configure, and maintain Void Linux systems

The "Void" is important. This specific "system maintenance" via XBPS commands is exactly what 4. XBPS Package Manager takes care of, after 2. Installation and 3. Configuration.

My initial motivation was to slip in sth about periodical --clean-cache, because I saw a reddit post and checked it, also with the docs. The cache is mentioned beside the man page link to xbps-remove, but it is up to the user to draw conclusions. The subtle problem behind it is, after cache cleaning, you have less to downgrade back to. But the solution is not to be silent and hope it will never overfill.

Then the "Switch to LTS series" question. IMO the only "trick" is to ignorepkg=linux, to deactivate the base-system dep, which is there for a good reason. "Ignoring Packages" in 4.1 Advanced Usage walks you through exactly that situation:

For example, you may wish to use doas(1) instead of sudo(8), but will be unable to remove the sudo package due to it being a dependency of the base-system package. To remove it, you will need to ignore the sudo package.

But now all this quite basic XBPS is repeated in 3. Configuration, 11. Kernel. One solution would be to mention xbps itself and the kernel as special packages: xbps can need a second update (and there is a static version), and the kernel is a package with "choices" (series, LTS, even DKMS) and a important (boot!) install-hook.

("Kernel configuration" is double unlucky: I associate this with kconfig, and I see the contents as a part of Void system maintenance via XBPS.)

xbps-reconfigure -f linux<x>.<y> is shown twice, once with xbps-alternatives and below with Install hooks.

install-hooks...Now I realise why I never found this:

 * Executes the post ACTION on its INSTALL script (which can be shown by
 running `xbps-query --property=install-script pkg' ).

It is in man xbps-reconfigure. "install-script" is not mentioned in man xbps-query or the docs.

I stop here, you can check my comments in 3 other issues by sorting by updates, and also check the one about TOC panel navigation (I closed it already, it is technical). Plus some of the threads on voidlinux subreddit.

This is the best summary I can make -- so I give up for the moment. I don't regret at all my research and efforts, and I hope you don't misunderstand my tone.

Review sections 3. Configuration, 4. XBPS Package Manager, 4.1 Advanced Usage, and 11. Kernel alongside the referenced XBPS man pages and related issues. First establish a focused scope and resolve the duplicated or missing explanations; done means the agreed XBPS maintenance guidance is coherent and no longer deadlocked.