Hi
The manpage of `sbuild` starts out with the synopsis which is a wall of
text that takes up an entire screen worth of all possible options you
can throw at `sbuild` (see attached screenshot).
I see this as a major information and mental overload dumped on users
trying to use `sbuild` and, in my view, this wall of text adds no value:
1. It does not help me with basic work flows for `sbuild`. Here a
curated and opinionated lists of `sbuild` commands would be better
(see `man pbuilder` or `man debputy` for examples)
2. It does not help me with finding any option that I might need
quickly. Even if I was an expert and was just looking for a concrete
option, this synopsis is so dense that I would struggle finding what
I am looking for.
Note that `sbuild --help` is implemented as `man sbuild`, so users do
not have any alternative and less heavy synopsis.
Please consider what you want to use the synopsis for and then optimize
for that use-case. I hope you would optimize for 1., since I feel that
is most valuable since that will help people getting started with
`sbuild`. Whereas use case 2., the experienced user probably have an
idea of what they are looking for and are better positioned to figure
search terms.
Assuming you go for 1., please consider the following points:
* How do I create a chroot?
- Maybe with variants for different dists.
* How do I maintain (update) a chroot?
* How do I build a package given a .dsc in a chroot?
* How do I build a package from an unpacked source package
(or git tree)?
- Maybe with variants for "get a debug shell on error"
Perhaps with some cross-cutting "spice" in the form of
[--chroot-mode=unshare] to hint to the fact that non-sudo/non-root modes
are available via unshare (ideally, it would be the default, but that is
a story for another).
I am not blind to the fact that there *is* a very short example of how
to build packages via sbuild (from unpacked source trees or .dsc files).
It is hidden near the end of the manpage (98% into the file according to
less). I think this kind of example belong in the synopsis and then the
EXAMPLES could expand on the synopsis (if there was something to add).
Specialized QA workflows like `piuparts` and `autopkgtests` could
probably be moved to a separate manpage like `sbuild-piuparts` and
`sbuild-autopkgtests` or even `sbuild-post-build-qa` for a combined one
and have their own synopsis if needed be. Personally, I am leaving these
features for my salsa-ci, so they are a secondary use-case for me.
Best regards,
Niels
PS: If you want 2., I honestly think the sheer number of options means
you need a separate appendix for them where you can write them out one
per line or in groups like `Lintian related options`, `Hook related
options`, etc. That is only solution I can come up with that makes this
"blob" of options somewhat manageable.