On 29/09/2025 11:33, Alejandro Colomar wrote:
Hi Arsen,
On Mon, Sep 29, 2025 at 11:46:21AM +0200, Arsen Arsenović wrote:
Unfortunately, it is. A collection of linear mostly-unrelated pages in
predetermined shape simply cannot document complex software, a
hierarchical approach is non-negotiable.
libc, (most of) the syscall API and coreutils are a lucky case in that
they are, fundamentally, large collections of *very* simple bits
(functions and programs),
Luckily, we're discussing the documentation of coreutils. :-)
The subject said "GNU" so I was intentionally speaking in generalities.
Oops, I intended to write GNU coreutils, but it seems I accidentally
omitted coreutils. My bad.
I'll start by importing the GNU coreutils manual pages in a branch of
the Linux man-pages project, to be able to work on them from time to
time, and when I have them in good shape, I'll propose their inclusion
in GNU coreutils.git. Does that sound good?
man pages are not currently in git, only distributed in release tarballs
(for cases where one can't generate man pages on the build host).
So any changes would need to be merge back into the utilities themselves,
so that their --help would be consistent. This issue would be multiplied
with translations. So I'm wary of a separate man page repo TBH.
Perhaps we could have a 3 tier setup with --help showing very summarized info,
man pages for more complete discussions, and info/html for the full docs.
I'm not convinced of the need for that though.
cheers,
Padraig
