4. XBPS Package Manager documentation is deadlocked

[sam6816]

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.

[Duncaen]

There will always be duplication to some level, like with commands like xbps-reconfigure, but that is because its runs different tasks for thousands of different packages, where some have special and more common use cases like the configuring the initramfs or the locales.

Users come to us with questions like "how do i switch to the lts kernel", they can look this up in the handbook or will be linked to the handbook instead of telling them to read the xbps man pages. The goal is to have accessible documentation so that new users can get started and get a general overview, if we would just document xbps we could just throw away the handbook since xbps already has man pages.

[Duncaen]

I have a hard time to fully understand what you are trying to say to be honest. I think the main point is for me that the documentation is to answer common questions users have, users who generally don't read full documentations, they have a simple question and they want an answer for that, instead of having to read pages of documentation which might lead them to discover the answer for themselves.

Documenting how to "maintain" a void system might duplicate some documentation that can be found in the XBPS section, but the goal is to convey as much information in as little documentation as possible, while providing users with the information they actually need to get started.

[sam6816]

I guess we agree that "Update" with xbps-install -Su is the first and most important message in the XBPS section. And at the same time it is the way to maintain void. There is no need to add a "maintenance section" to the handbook, it is already there, from "Updating" to "Virtual Packages". "Finding Files and Packages" is after "Updating". Advanced Usage continues with "Downgrading", "Holding", "Repo locking", "Ignoring" and "Virtual".

Why is "Ignoring" advanced, and cache cleaning not even mentioned? "Ignoring" should be more prominent. Then 3.11 Kernel could refer to it and vice versa.

For non-manpage users, a simple example with query, install and remove could integrate all 3 commands. (instead of discussing xlocate). Show how easy it is to use, but also list the maintenance aspects (-Su, cache, orphans).

[sam6816]

It all shows in this core message, right after the xbps-command list:

Updating

Like any other system, it is important to keep Void up-to-date. Use xbps-install(1) to update:

# xbps-install -Su

Even when you've just read all the man pages, you have to follow the order "use xbps-install!". There is no real explanation given. It sounds like "even with MS Windows there are updates". The message is important and at the right spot, but it should be expanded and harmonized.

Similar to cache and orphans, which are even extra mentioned, but without advice about usage.

Maybe I could define it as creating a higher-level man xbps (without the .d). Similar to man git. Or %cough% systemd. The motto would be "Package Management according to XBPS". Not to re-chew the man pages, but to show the bigger picture.

[sam6816]

The guidelines say:

Outside of the 'installation' sections, step-by-step instructions containing 'magic' commands for copying-and-pasting are strongly discouraged. Users are expected to read the canonical documentation (e.g. man pages) for individual programs to understand how to use them, rather than relying on copying-and-pasting.

It is this non-man page "canonical" documentation I try to define. This intro to 3.11 Kernel configuration I don't like:
xbps-query --regex -Rs '^linux[0-9.]+-[0-9._]+'

Isn't this a magical command? I would prefer a short explanation about the naming of kernel packages in void, and then a simple "canonical" command like xbps-query -Rs linux4 is enough. The ones who need to be told about "regex" are rather beginners who try to fine tune a repo search for a normal package.

"Told about regex" does NOT mean a long or even short explanation! Drop the name, give one useful example, done.

So above kernel query should be harmonized, as I call it, with "Finding Files and Packages" in the basic, canonical part.