On Sun, 16 Feb 2025, 14:51 Johannes Schauer Marin Rodrigues, <
jo...@debian.org> wrote:
> I intend to do a major rewrite of the first part of the man
> page for Trixie.
I think the man-page for sbuild is no worse than other docs in debian
(which doesnt say much, but i dont think you should worry too much about it
- i started from no knowledge of sbuild and perl and sbuild(1) helped me a
lot!)
The bits i would change are
- dont list every option in SYNOPSIS, and better explain what the input is
-- i think this is the
hardest thing for a newcomer to understand
because even the concept of a .dsc is not
familiar.
- some options are in SYNOPSIS but not described anywhere else (eg --log /
--nolog)
- some options like --archive and --batch and --mode=buildd are not clearly
described
- the links between --clean / --source / --force-orig-source are not
clearly described
- the various binnmu-related options would benefit from an example -- i
assume they may make sense to an expert, but they are a hard read for me.
- several places dont say what the default is
- several places refer to paths but do not say
if it is a path on the host or in the chroot
- some places assume the default is schroot
- change the emphasis from term "external command" to the more standard
"hook"
- list the options in a more logical order
- usual grammar/idiom fixes and removal of duplication
(i have a local patch that makes '--help' more useful as well)
The man-page for sbuild.conf is quite hard to follow because it talks about
all-caps things that are implementation details rather than saying what you
put into the file. i generally dont read this one at all as it is too
confusing. i think a real editor would want to move content between the 2
man-pages, leaving a shorter sbuild.1. But that would be a lot of work.
The other docs and readmes are definitely old as they assume schroot, but
they are so hard ro discover it doesnt hurt! i think you could delete
most.of them.
