Re: Move GNU manual pages to the Linux man-pages project

["Arsen Arsenović" <arsen@aarsen.me>]

[-- Attachment #1: Type: text/plain, Size: 4936 bytes --]

Hi Alex,

Alejandro Colomar <alx@kernel.org> writes:

> [[PGP Signed Part:No public key for EB89995CC290C2A9 created at 2025-09-21T14:53:21+0200 using RSA]]
> Hi Arsen,
>
> On Sun, Sep 21, 2025 at 02:02:16PM +0200, Arsen Arsenović wrote:
>> IMO, docs should not be outsourced from the project they correspond to.
>> Doing so makes them harder to install and keep accurate to the installed
>> version of what they target.
>
> I could maintain them within the coreutils repo, if that's preferred.

That'd be significantly better, yes, if by that you mean that they'd
become part of the coreutils (et al) distribution.

>> > I understand GNU's stance on manual pages, and that you might not be
>> > interested in improving them much, but maybe you're open to them being
>> > improved elsewhere.
>> 
>> It's frankly better to improve them inline.  But I'd rather see us move
>> past the woefully inadequate 'man' documentation system,
>
> I disagree with man(1) being inadequate.  :)

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), but the fact that manpages are insufficient is
visible in everything about Linux other than the syscall API.  Finding
documentation for Linux cmdline parameters, pseudo-FSes and various
components is a Herculean task.  In the unfortunate case that the
documentation is in a manpage, the manpages are excessively long and
entirely in-navigable due to a lack of structure, or broken up into many
tiny pages that are annoying to navigate (though, you said that this
might be improving with a .MR macro, so that's nice).

>> for instance by
>> providing an info viewer users are more likely to find usable (though, I
>> struggle to see why the current standalone info viewer is so
>> problematic, especially since I taught multiple people who got the hang
>> of it fairly easily).  Installing pages with a richer markup (HTML
>> perhaps, or a new format that can be easily rendered on-the-fly to
>> reflowable text or HTML) would also be nice.  The current format is one
>> of lightly marked up catfiles, and so isn't great in modern
>> environments.
>
> I think what you don't like of man(7) documentation is man(1) and not
> man(7).  A more featureful man(1) viewer could be developed, and some
> people have attempted to build one, where key bindings could for example
> show an index of a page.

No, it's both.  The 'man' macro package is imperative and unstructured
rather than declarative and structured, and 'roff' is quite cumbersome
to use.  The BSDs (I think?) have attempted to solve this partially with
mdoc.  I've found authoring with it slightly better.  Unfortunately,
however, it is still 'roff'.

But, indeed, pagers are inadequate viewers also.  OpenBSD, IIRC,
provided slight improvement in this regard by letting 'less' read some
type of list of tags that it produces out of the manual page, or
somesuch, to facilitate jumping.  This is a significant move in the
right direction, but it doesn't manage to address the fact that manpages
are non-hierarchical.

> Jumping from one page to another will also be possible soon, with the
> recently added .MR macro for manual-page references.  (And in the PDF
> book, we already have that in old pages, with some heuristics that work
> reasonably well.)

I am glad to hear that.

>> Given that coreutils manpages are generated from help text, adding a
>> paragraph to the tsort help text would probably suffice (see sort for an
>> example).
>> 
>> > The Linux man-pages project already documents the GNU C library, so it
>> > wouldn't be extraneous to also take ownership of the coreutils manual
>> > pages.
>> 
>> And it's a source of problems; they don't always correspond to the
>> installed version of the libc,
>
> That's not very important.  The manual pages keep old information, so as
> long as you have the latest pages, they're good for whatever glibc is
> installed.  Of course, we are missing a few pages, but there are few.
> And of course, if you have bleeding edge glibc, there are more chances
> some details may be missing.

This addresses half of the issue (what if the pages are old?), and still
leaves the fact its a separate software distribution unsolved.

>> don't get installed with libc, and have
>> lead to the actual manual being somewhat forgotten.
>
> In general, the manual pages are more accurate than glibc's own manual,
> as even some glibc maintainers have acknowledged in the past, so I
> wouldn't worry much about this.

That is precisely the problem I was referring to.

Have a lovely day!
-- 
Arsen Arsenović

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 251 bytes --]