Move GNU manual pages to the Linux man-pages project

Move GNU manual pages to the Linux man-pages project

[Alejandro Colomar]

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

Hi!

GNU coreutils manual pages are to some degree incomplete.  I was told
today that "tsort(1) is a bad joke".  I wonder if you'd be interested in
moving the maintenance of the manual pages of GNU coreutils to the Linux
man-pages project, where I could take care of them, and improve their
contents.

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.

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.

What do you think?


Have a lovely day!
Alex

-- 
<https://www.alejandro-colomar.es>
Use port 80 (that is, <...:80/>).

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

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

[Sam James]

Alejandro Colomar <alx@kernel.org> writes:

> Hi!
>
> GNU coreutils manual pages are to some degree incomplete.  I was told
> today that "tsort(1) is a bad joke".  I wonder if you'd be interested in
> moving the maintenance of the manual pages of GNU coreutils to the Linux
> man-pages project, where I could take care of them, and improve their
> contents.
>
> 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.
>
> 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.

But GNU coreutils isn't Linux specific.

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

[Alejandro Colomar]

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

Hi Sam,

On Sat, Sep 20, 2025 at 05:27:17PM +0100, Sam James wrote:
> Alejandro Colomar <alx@kernel.org> writes:
> 
> > Hi!
> >
> > GNU coreutils manual pages are to some degree incomplete.  I was told
> > today that "tsort(1) is a bad joke".  I wonder if you'd be interested in
> > moving the maintenance of the manual pages of GNU coreutils to the Linux
> > man-pages project, where I could take care of them, and improve their
> > contents.
> >
> > 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.
> >
> > 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.
> 
> But GNU coreutils isn't Linux specific.

Hmmm, true.  You can install the man1/ pages with `make install-man1`,
though, so it's not a big deal.

I see the packaging complication, though, by having the package split
into two upstream packages.


Have a lovely day!
Alex

-- 
<https://www.alejandro-colomar.es>
Use port 80 (that is, <...:80/>).

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

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

[Alejandro Colomar]

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

On Sat, Sep 20, 2025 at 05:27:17PM +0100, Sam James wrote:
> Alejandro Colomar <alx@kernel.org> writes:
> 
> > Hi!
> >
> > GNU coreutils manual pages are to some degree incomplete.  I was told
> > today that "tsort(1) is a bad joke".  I wonder if you'd be interested in
> > moving the maintenance of the manual pages of GNU coreutils to the Linux
> > man-pages project, where I could take care of them, and improve their
> > contents.
> >
> > 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.
> >
> > 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.
> 
> But GNU coreutils isn't Linux specific.

(BTW, glibc isn't Linux-specific either.  There's GNU Hurd, and I
 welcome patches for it.)


Cheers,
Alex

-- 
<https://www.alejandro-colomar.es>
Use port 80 (that is, <...:80/>).

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

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

[Pádraig Brady]

On 20/09/2025 17:08, Alejandro Colomar wrote:
> Hi!
> 
> GNU coreutils manual pages are to some degree incomplete.  I was told
> today that "tsort(1) is a bad joke".  I wonder if you'd be interested in
> moving the maintenance of the manual pages of GNU coreutils to the Linux
> man-pages project, where I could take care of them, and improve their
> contents.
> 
> 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.
> 
> 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.
> 
> What do you think?

The man pages are programmatically generated from the sources.
I.e. $cmd --help is processed by help2man.

All of the man pages have links to the info docs for full documentation.

Any concise improvements for the man pages are gladly accepted,
but would be applied to the source (also for --help).

cheers,
Padraig

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

[Alejandro Colomar]

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

Hi Pádraig,

On Sat, Sep 20, 2025 at 05:34:03PM +0100, Pádraig Brady wrote:
> The man pages are programmatically generated from the sources.
> I.e. $cmd --help is processed by help2man.

Hmmm.  That's a problem.

> All of the man pages have links to the info docs for full documentation.

I know.  However, many users don't enjoy the info docs.

> Any concise improvements for the man pages are gladly accepted,
> but would be applied to the source (also for --help).

If I have any, I'll send them.  However, I wouldn't volunteer for
maintaining --help documentation.  :)


Have a lovely day!
Alex

-- 
<https://www.alejandro-colomar.es>
Use port 80 (that is, <...:80/>).

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

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

[Pádraig Brady]

On 20/09/2025 17:55, Alejandro Colomar wrote:
> Hi Pádraig,
> 
> On Sat, Sep 20, 2025 at 05:34:03PM +0100, Pádraig Brady wrote:
>> The man pages are programmatically generated from the sources.
>> I.e. $cmd --help is processed by help2man.
> 
> Hmmm.  That's a problem.
> 
>> All of the man pages have links to the info docs for full documentation.
> 
> I know.  However, many users don't enjoy the info docs.

I my experience user don't enjoy the info _reader_, while the docs are fine.
The full docs are on the web though and also linked from each man page.

cheers,
Padraig

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

[Alejandro Colomar]

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

Hi Pádraig,

On Sat, Sep 20, 2025 at 06:01:21PM +0100, Pádraig Brady wrote:
> > > All of the man pages have links to the info docs for full documentation.
> > 
> > I know.  However, many users don't enjoy the info docs.
> 
> I my experience user don't enjoy the info _reader_, while the docs are fine.
> The full docs are on the web though and also linked from each man page.

Yeah, the info online docs are much nicer.  However, I (and others)
don't enjoy going online for documentation, when offline documentation
is available.


Cheers,
Alex

> 
> cheers,
> Padraig

-- 
<https://www.alejandro-colomar.es>
Use port 80 (that is, <...:80/>).

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

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

[Collin Funk]

Alejandro Colomar <alx@kernel.org> writes:

> Hi Pádraig,
>
> On Sat, Sep 20, 2025 at 06:01:21PM +0100, Pádraig Brady wrote:
>> > > All of the man pages have links to the info docs for full documentation.
>> > 
>> > I know.  However, many users don't enjoy the info docs.
>> 
>> I my experience user don't enjoy the info _reader_, while the docs are fine.
>> The full docs are on the web though and also linked from each man page.
>
> Yeah, the info online docs are much nicer.  However, I (and others)
> don't enjoy going online for documentation, when offline documentation
> is available.

I wish distributions installed the HTML docs to
/usr/share/doc/coreutils, or somewhere similar (and substitute package
name for other packages). The gnu.org site is down or takes ages to load
frequently nowadays.

That said, I have seen complaints about the Coreutils man pages being
"incomplete". However, it is grown on me personally. I use the man pages
as a quick reference when I want to find an option or understand what it
does. And the info page for examples and/or commentary that is too long
to reasonably fit in --help.

Writing all of that in groff would be a pain. More of my time would be
spent understanding the syntax than it would be focusing on the content.
Texinfo's syntax is much more readable and easy to remember. And the
HTML and PDF output look nice to read.

I guess Markdown or reStructuredText would be more friendly to new
contributors since many do not know Texinfo. However, I haven't seen
good PDFs generated by them (though I concede that I very well could be
unaware of examples).

Collin

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

[Alejandro Colomar]

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

Hi Collin,

On Sat, Sep 20, 2025 at 01:05:52PM -0700, Collin Funk wrote:
> Alejandro Colomar <alx@kernel.org> writes:
> 
> > Hi Pádraig,
> >
> > On Sat, Sep 20, 2025 at 06:01:21PM +0100, Pádraig Brady wrote:
> >> > > All of the man pages have links to the info docs for full documentation.
> >> > 
> >> > I know.  However, many users don't enjoy the info docs.
> >> 
> >> I my experience user don't enjoy the info _reader_, while the docs are fine.
> >> The full docs are on the web though and also linked from each man page.
> >
> > Yeah, the info online docs are much nicer.  However, I (and others)
> > don't enjoy going online for documentation, when offline documentation
> > is available.
> 
> I wish distributions installed the HTML docs to
> /usr/share/doc/coreutils, or somewhere similar (and substitute package
> name for other packages). The gnu.org site is down or takes ages to load
> frequently nowadays.

While having offline HTML docs would be better than having online docs,
I really prefer something I can read comfortably from the terminal.
man(1) is really comfortable to find and use documentation.

And if I want to sit down and slowly read documentation --as opposed to
just consulting quickly a detail--, I can read it as PDF with pdfman(1),
which has essentially the same command line interface as man(1), but
opens the page on a PDF viewer.

> That said, I have seen complaints about the Coreutils man pages being
> "incomplete". However, it is grown on me personally. I use the man pages
> as a quick reference when I want to find an option or understand what it
> does. And the info page for examples and/or commentary that is too long
> to reasonably fit in --help.

I personally would remove documentation from help, and only print a
usage line.  The user is welcome to read the manual page for consulting
the documentation.

This is what I'd use in a command:

	Usage: foo [OPTIONS] FILE

> Writing all of that in groff would be a pain. More of my time would be
> spent understanding the syntax than it would be focusing on the content.
> Texinfo's syntax is much more readable and easy to remember. And the
> HTML and PDF output look nice to read.

I volunteer to maintain the man(7) source.  To me it's quite
comfortable.  When you get used to it, it's not bad.  The syntax is
actually quite simple.  You don't need to learn the full roff(7)
language; the man(7) macros are quite small compared to it.  mdoc(7) is
much more complex than man(7), for comparison.

The PDF output of man(7) also looks nice.  Please have a look at the
PDF book of the Linux manual pages:
<https://mirrors.edge.kernel.org/pub/linux/docs/man-pages/book/man-pages-6.15.pdf>

Or you can read single-page PDFs by running pdfman(1), which some
distros already package, or you can find pdfman(1) in the man-pages.git
repo (it's a shell script).

HTML is not yet good, although groff maintainers are slowly improving
it.

And the build system of the Linux man-pages has a lot of lints to make
sure the man(7) source code is of the highest quality, apart from also
helping catch easy mistakes.

> I guess Markdown or reStructuredText would be more friendly to new
> contributors since many do not know Texinfo. However, I haven't seen
> good PDFs generated by them (though I concede that I very well could be
> unaware of examples).

I doubt Markdown or RST would be good for quality documentation.


Have a lovely night!
Alex

-- 
<https://www.alejandro-colomar.es>
Use port 80 (that is, <...:80/>).

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

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

[Collin Funk]

Alejandro Colomar <alx@kernel.org> writes:

>> That said, I have seen complaints about the Coreutils man pages being
>> "incomplete". However, it is grown on me personally. I use the man pages
>> as a quick reference when I want to find an option or understand what it
>> does. And the info page for examples and/or commentary that is too long
>> to reasonably fit in --help.
>
> I personally would remove documentation from help, and only print a
> usage line.  The user is welcome to read the manual page for consulting
> the documentation.
>
> This is what I'd use in a command:
>
> 	Usage: foo [OPTIONS] FILE

Interesting, I like the documentation in --help. Regardless, it is part
of the GNU Coding Standards [1]:

    The standard --help option should output brief documentation for how
    to invoke the program, on standard output, then exit successfully.
    Other options and arguments should be ignored once this is seen, and
    the program should not perform its normal function.

My reading is that the mention of "documentation" implies more than a
usage line. One can try to change the standards through the
bug-standards@gnu.org, but I do not think you will have much luck in
this case.

>> Writing all of that in groff would be a pain. More of my time would be
>> spent understanding the syntax than it would be focusing on the content.
>> Texinfo's syntax is much more readable and easy to remember. And the
>> HTML and PDF output look nice to read.
>
> I volunteer to maintain the man(7) source.  To me it's quite
> comfortable.  When you get used to it, it's not bad.  The syntax is
> actually quite simple.  You don't need to learn the full roff(7)
> language; the man(7) macros are quite small compared to it.  mdoc(7) is
> much more complex than man(7), for comparison.

mdoc is the format mandoc uses for the different BSD man pages, correct?

> The PDF output of man(7) also looks nice.  Please have a look at the
> PDF book of the Linux manual pages:
> <https://mirrors.edge.kernel.org/pub/linux/docs/man-pages/book/man-pages-6.15.pdf>
>
> Or you can read single-page PDFs by running pdfman(1), which some
> distros already package, or you can find pdfman(1) in the man-pages.git
> repo (it's a shell script).

It looks good, but I still prefer the Texinfo PDFs.

Collin

[1] https://www.gnu.org/prep/standards/standards.html#g_t_002d_002dhelp

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

[Alejandro Colomar]

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

Hi Collin,

On Sat, Sep 20, 2025 at 04:02:28PM -0700, Collin Funk wrote:
> > This is what I'd use in a command:
> >
> > 	Usage: foo [OPTIONS] FILE
> 
> Interesting, I like the documentation in --help. Regardless, it is part
> of the GNU Coding Standards [1]:
> 
>     The standard --help option should output brief documentation for how
>     to invoke the program, on standard output, then exit successfully.
>     Other options and arguments should be ignored once this is seen, and
>     the program should not perform its normal function.
> 
> My reading is that the mention of "documentation" implies more than a
> usage line. One can try to change the standards through the
> bug-standards@gnu.org, but I do not think you will have much luck in
> this case.

Yup, I don't intend to change that.  It's just my personal preference.

> >> Writing all of that in groff would be a pain. More of my time would be
> >> spent understanding the syntax than it would be focusing on the content.
> >> Texinfo's syntax is much more readable and easy to remember. And the
> >> HTML and PDF output look nice to read.
> >
> > I volunteer to maintain the man(7) source.  To me it's quite
> > comfortable.  When you get used to it, it's not bad.  The syntax is
> > actually quite simple.  You don't need to learn the full roff(7)
> > language; the man(7) macros are quite small compared to it.  mdoc(7) is
> > much more complex than man(7), for comparison.
> 
> mdoc is the format mandoc uses for the different BSD man pages, correct?

Yes, the BSDs use mdoc(7) instead of man(7).  Some Linux projects also
use it (for example, nginx), but they're minoritary.

> > The PDF output of man(7) also looks nice.  Please have a look at the
> > PDF book of the Linux manual pages:
> > <https://mirrors.edge.kernel.org/pub/linux/docs/man-pages/book/man-pages-6.15.pdf>
> >
> > Or you can read single-page PDFs by running pdfman(1), which some
> > distros already package, or you can find pdfman(1) in the man-pages.git
> > repo (it's a shell script).
> 
> It looks good,

I'm glad you like them.  :)

> but I still prefer the Texinfo PDFs.

Makes sense.  I don't intend to replace that.  I think it would be nice
to provide both.  Some details might not be necessary in the manual
pages, I agree, so they can be a short version of the info manual, but
the current ones are too lacking, IMO, and having them tied to --help
makes it hard to make them useful, since I also wouldn't want to expand
--help much more than what it currently is, and also maintaining
generated manual pages is less than ideal.


Have a lovely day!
Alex

> 
> Collin
> 
> [1] https://www.gnu.org/prep/standards/standards.html#g_t_002d_002dhelp

-- 
<https://www.alejandro-colomar.es>
Use port 80 (that is, <...:80/>).

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

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

[Collin Funk]

William Bader <williambader@hotmail.com> writes:

>> I guess Markdown or reStructuredText would be more friendly to new contributors since many do not know Texinfo.
>
> Pandoc https://pandoc.org/ can convert between a number of formats. In
> theory, it can convert markdown and rst to texinfo. Maybe with care it
> would be possible to come up with a set of conventions for markdown,
> maybe with a preprocessing pass, to have pandoc produce texinfo that
> can print well.

I have heard the name, but I have never used it.

Sphinx, used by Python [1] and the Linux Kernel [2], creates nice
searchable HTML pages. Apparently there is an experimental Texinfo
converter [3]. I don't see most GNU projects using anything that doesn't
create good info pages, though. Although some have mentioned not liking
the 'info' reader, I find the one in Emacs to be nice to use.

GCC switched to Sphinx for a very short period and then reverted the
pages, if I remember correctly. See mailing list drama involved in that
change [4].

Collin

[1] https://docs.python.org/3/
[2] https://www.kernel.org/doc/html/latest/
[3] https://mysphinx.readthedocs.io/en/latest/faq.html#texinfo-info
[4] https://inbox.sourceware.org/gcc/1a22bc37-3d48-132f-a3d5-219471cd443c@suse.cz/

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

[Michael Greenberg]

On 2025-09-20 at 10:31:31 PM, William Bader wrote:

[snip]
>> I guess Markdown or reStructuredText would be more friendly to new
>> contributors since many do not know Texinfo.
>
> Pandoc https://pandoc.org/ can convert between a number of formats. In
> theory, it can convert markdown and rst to texinfo. Maybe with care it
> would be possible to come up with a set of conventions for markdown,
> maybe with a preprocessing pass, to have pandoc produce texinfo that
> can print well.

I've been very happy using pandoc to generate manpages from Markdown for
ffs:

 - Markdown: <https://github.com/mgree/ffs/blob/main/docs/ffs.1.md>
 - Makefile to generate manpage: <https://github.com/mgree/ffs/blob/main/man/Makefile>
 - Output: <https://github.com/mgree/ffs/blob/main/man/ffs.1>

I haven't tried generating texinfo (I quite dislike the info reader and
avoid using it), but I suspect the output would be satisfactory. While I
understand the GNU bias in favor of info, I would support any efforts to
improve the manpages (which are, imo, more accessible).

Cheers,
Michael

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

[Jakub Wilk]

* Pádraig Brady <P@draigBrady.com>, 2025-09-20 18:01:
>I my experience user don't enjoy the info _reader_, while the docs are 
>fine.

If you've been avoiding info docs because of the horrors of the info(1) 
user interface (like I had been doing for 20 years or so), you should 
give https://github.com/jwilk/informan a try.

-- 
Jakub Wilk

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

[Alejandro Colomar]

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

Hi Jakub,

On Sat, Sep 20, 2025 at 07:42:49PM +0200, Jakub Wilk wrote:
> * Pádraig Brady <P@draigBrady.com>, 2025-09-20 18:01:
> > I my experience user don't enjoy the info _reader_, while the docs are
> > fine.
> 
> If you've been avoiding info docs because of the horrors of the info(1) user
> interface (like I had been doing for 20 years or so), you should give
> https://github.com/jwilk/informan a try.

Hmm, I'll try!  How does it compare to piping to less as this?:

	$ info libc | less;

BTW, to someone who doesn't know perl, how do I install the File::Which
module?

	$ ./informan libc;
	Can't locate File/Which.pm in @INC (you may need to install the File::Which module) (@INC entries checked: /etc/perl /usr/local/lib/x86_64-linux-gnu/perl/5.40.1 /usr/local/share/perl/5.40.1 /usr/lib/x86_64-linux-gnu/perl5/5.40 /usr/share/perl5 /usr/lib/x86_64-linux-gnu/perl-base /usr/lib/x86_64-linux-gnu/perl/5.40 /usr/share/perl/5.40 /usr/local/lib/site_perl) at ./informan line 20.
	BEGIN failed--compilation aborted at ./informan line 20.

apt-file(1) didn't help:

	$ apt-file find Find::Which;
	$


Have a lovely night!
Alex

-- 
<https://www.alejandro-colomar.es>
Use port 80 (that is, <...:80/>).

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

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

[Collin Funk]

Alejandro Colomar <alx@kernel.org> writes:

> Hmm, I'll try!  How does it compare to piping to less as this?:
>
> 	$ info libc | less;
>
> BTW, to someone who doesn't know perl, how do I install the File::Which
> module?

On Debian:

    $ sudo apt install libfile-which-perl

On Fedora:

    $ sudo dnf install perl-File-Which

You could also install it through 'cpan' but that is more effort.

Collin

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

[Bernhard Voelker]

On 9/20/25 7:42 PM, Jakub Wilk wrote:
> * Pádraig Brady <P@draigBrady.com>, 2025-09-20 18:01:
>> I my experience user don't enjoy the info _reader_, while the docs are fine.
> 
> If you've been avoiding info docs because of the horrors of the info(1) user interface (like I had been doing for 20 years or so), you should give https://github.com/jwilk/informan a try.


My distro has 'pinfo' installed.  I like that better than raw 'info'.

Have a nice day,
Berny

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

[Chuck Wolber]

On Sat Sep 20, 2025 at 5:01 PM UTC, Pádraig Brady wrote:
> On 20/09/2025 17:55, Alejandro Colomar wrote:
>> 
>> I know.  However, many users don't enjoy the info docs.
>
> I my experience user don't enjoy the info _reader_, while the docs are fine.

And that is all it takes to kill the value.

Perhaps I am unusual, but I typically only pull up documentation when I am deep
into a problem and need a specific answer. My brain is already full of problem
details and I have little left for an interface that requires more than a token
amount of navigation effort.

Man pages are great this way. Like any documentation, they almost never contain
_exactly_ what I need, but they are good enough, and navigation is trivial.

Anytime I hit the bottom of a man page and there is a reference to additional
detail in an info page, my next step is a search engine.

..Ch:W..

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

[Arsen Arsenović]

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

Alejandro Colomar <alx@kernel.org> writes:

> [[PGP Signed Part:No public key for EB89995CC290C2A9 created at 2025-09-20T18:08:35+0200 using RSA]]
> Hi!
>
> GNU coreutils manual pages are to some degree incomplete.  I was told
> today that "tsort(1) is a bad joke".  I wonder if you'd be interested in
> moving the maintenance of the manual pages of GNU coreutils to the Linux
> man-pages project, where I could take care of them, and improve their
> contents.

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 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, 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.

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, don't get installed with libc, and have
lead to the actual manual being somewhat forgotten.

> What do you think?
>
>
> Have a lovely day!
> Alex

-- 
Arsen Arsenović

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

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

[Alejandro Colomar]

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

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.

> > 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.  :)

> 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.

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.)

> 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.

> 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.


Have a lovely day!
Alex

-- 
<https://www.alejandro-colomar.es>
Use port 80 (that is, <...:80/>).

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

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

[Arsen Arsenović]

[-- 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 --]

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

[Alejandro Colomar]

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

Hi Arsen,

On Thu, Sep 25, 2025 at 04:04:50PM +0200, Arsen Arsenović wrote:
> 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'd guess that if the pages are within the coreutils.git repo, the build
system will package them with the rest of the distribution, so yes.

However, I'm unable to deal with autotools, so that would need to be
handled by some of you.  But yes, that's the idea.

I can maintain the contents of the pages.

> >> > 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),

Luckily, we're discussing the documentation of coreutils.  :-)

(Actually, git(1) also has more-or-less hierarchical manual pages for
 documentation, and it works quite well, IMO.  But I agree it's not
 always the case.  PCRE is a counter-example, where I can't find
 anything.)

[...]
> >> 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?),

A solution for old pages is cloning them from the upstream repo, and
running 'make && sudo make install'.  But that's not for everybody.

Alternatively, kindly ask your distribution manager to package a recent
version of the pages.  After all, they're just text, so stability isn't
very important.

> and still
> leaves the fact its a separate software distribution unsolved.

The issue there is that the distinction between manual pages for the
kernel and for glibc isn't very clear.  That's why we have one project
that covers all, instead of duplicating the information, or having
incomplete information in either side.

But that's not an issue in coreutils, as we could have them distributed
with the binaries.

> >> 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.

Ah, I thought you were worried users would forget about it.  If the
maintainers forget about it, that's a problem for users of info manuals,
indeed.

> 
> Have a lovely day!

You too!  :-)

Alex

> -- 
> Arsen Arsenović



-- 
<https://www.alejandro-colomar.es>
Use port 80 (that is, <...:80/>).

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

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

[Arsen Arsenović]

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

Hi Alex,

Alejandro Colomar <alx@kernel.org> writes:

>> That'd be significantly better, yes, if by that you mean that they'd
>> become part of the coreutils (et al) distribution.
>
> I'd guess that if the pages are within the coreutils.git repo, the build
> system will package them with the rest of the distribution, so yes.
>
> However, I'm unable to deal with autotools, so that would need to be
> handled by some of you.  But yes, that's the idea.
>
> I can maintain the contents of the pages.

That's alright, I'm sure.

>> 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.

> (Actually, git(1) also has more-or-less hierarchical manual pages for
>  documentation, and it works quite well, IMO.  But I agree it's not
>  always the case.  PCRE is a counter-example, where I can't find
>  anything.)

Git falls back to the "Pro Git" book also.  IMO manuals should largely
be like the "Pro Git" book, but also incorporating references (git is
near this but splits the two, as you know).

> [...]
>> >> 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?),
>
> A solution for old pages is cloning them from the upstream repo, and
> running 'make && sudo make install'.  But that's not for everybody.
>
> Alternatively, kindly ask your distribution manager to package a recent
> version of the pages.  After all, they're just text, so stability isn't
> very important.

The latter is probably fine, but you clarified you intend to keep them
in coreutils' distribution, so that solves that issue.

>> and still
>> leaves the fact its a separate software distribution unsolved.
>
> The issue there is that the distinction between manual pages for the
> kernel and for glibc isn't very clear.  That's why we have one project
> that covers all, instead of duplicating the information, or having
> incomplete information in either side.

The division between the two is somewhat unique to free software
projects, so I can see the struggle :-)

> But that's not an issue in coreutils, as we could have them distributed
> with the binaries.
>
>> >> 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.
>
> Ah, I thought you were worried users would forget about it.  If the
> maintainers forget about it, that's a problem for users of info manuals,
> indeed.

Yep ;)
-- 
Arsen Arsenović

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

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

[Alejandro Colomar]

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

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?


Have a lovely day!
Alex

-- 
<https://www.alejandro-colomar.es>
Use port 80 (that is, <...:80/>).

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

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

[Arsen Arsenović]

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

Hi,

Alejandro Colomar <alx@kernel.org> writes:

> 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?

That's up to Pádraig, really, not me.

I just ask that you don't publish them in the interim to avoid the issue
with documentation being neglected.
-- 
Arsen Arsenović

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

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

[Alejandro Colomar]

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

On Mon, Sep 29, 2025 at 11:26:56PM +0200, Arsen Arsenović wrote:
> Hi,

Hi Arsen,

> Alejandro Colomar <alx@kernel.org> writes:
> 
> > 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?
> 
> That's up to Pádraig, really, not me.

Okay.

> I just ask that you don't publish them in the interim to avoid the issue
> with documentation being neglected.

Agreed; they won't be published.  They'll live in a branch in my home
cgit server, but won't publish them anywhere (not even a branch at
<kernel.org>).


Have a lovely night!
Alex

-- 
<https://www.alejandro-colomar.es>
Use port 80 (that is, <...:80/>).

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

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

[Pádraig Brady]

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

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

[Alejandro Colomar]

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

Hi Pádraig,

On Mon, Sep 29, 2025 at 10:41:56PM +0100, Pádraig Brady wrote:
> 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).

I know.  I've copied them from what Debian installs, for the moment, for
working on them.

> 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.

My idea is to have them under source control in the coreutils.git repo,
not a separate repo.

> 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.

Yup, this is what I have in mind.

> I'm not convinced of the need for that though.

I'll work anyway on that, as some people have come to me in private
asking for it, and suggesting me to fork and improve.  I'll fork,
indeed, but without intention to publish.  Once I have decent manual
pages, I'll offer them to be incorporated into coreutils.git.


Have a lovely night!
Alex

-- 
<https://www.alejandro-colomar.es>
Use port 80 (that is, <...:80/>).

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

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

[Pádraig Brady]

On 30/09/2025 00:27, Alejandro Colomar wrote:
> I'll work anyway on that, as some people have come to me in private
> asking for it, and suggesting me to fork and improve.  I'll fork,
> indeed, but without intention to publish.  Once I have decent manual
> pages, I'll offer them to be incorporated into coreutils.git.

Cool,

We'll incorporate any improvements.

Much appreciated.

thanks,
Padraig

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

[Bernhard Voelker]

On 9/30/25 12:12 PM, Pádraig Brady wrote:
> We'll incorporate any improvements.
> 
> Much appreciated.

yes, having people concentrating on the documentation is great.

 From a process perspective - sorry, business language -, what does this mean exactly?
E.g. if we add a new option to the tool, i.e., to the sources, then the same
commit would add:
[X] tests,
[X] the NEWS entry,
[X] amend the usage() string for --help,
but leave man+texi left aside, and hope that the new option is not missed
by the docs sub-team?

Or do we adjust the texi manual as well, and only leave man behind?
Or?

I'm still not really convinced that having 3 formats for documentation (terse --help
output, comprehensive man pages and the texinfo manual) is effectively using our resources,
even with a docs sub-team.
There'll be redundancy of documentation in man vs. texi which yields a large chance to
diverge, i.e., to omit details in the one or the other format, or - even worse - that
the content of one format contradict to the other.
How do we ensure + verify that this doesn't happen?
As long as there's no "single truth" of documentation, and all the other formats
(man, pdf, html, info, ...) get generated out of that, I don't see how we could
do that.
And at least the given man structure (synopsis, ..., see also) seems to be more
limited than what the mor enatural navigation in Texinfo-based documentation (info,
pdf, html, ...) allows.

Finally, as someone mentioned: the translation results are linked somewhere into the upstream
release and the downstream build process.  How would that change?

That said, I don't currently want to think where the man pages are stored (separate git repo
or included), and it's more important how such a documentation change modifies the
development process, how it decreases effort while still improving the consistency of the
documentation for the user.

Have a nice day,
Berny

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

[Rob Landley]

On 9/25/25 09:04, 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),

It wasn't "lucky". "Do one thing and do it well" was an explicit design 
decision the Bell Labs guys made in 1971. Doug McIlroy wrote about it in 
1978 in the Forward to the article on "The Unix TimeSharing System" in 
the Bell System Technical Journal in 1978: "do one thing and do it well" 
and then compose more complicated things from simple parts. Peter Salus 
reiterated it in "a quarter century of unix" (a book about the 
anniversary), and Mike Gancarz' book "the unix philosophy" went into 
this in some detail.

That's why they could get away with a flat namespace and simple man 
pages and so on for decades.

Gnu's Not Unix in quite a number of ways.

> 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.

The utility command line parameters are on the web at 
https://man7.org/linux/man-pages/man1/intro.1.html which seemed 
reasonably straightforward to me. (Over the years it's accumulated a lot 
of extra crap from optional packages, but as failure modes go it could 
be worse...)

The kernel command line arguments are at 
https://kernel.org/doc/Documentation/admin-guide/kernel-parameters.txt 
and filesystems are at 
https://kernel.org/doc/Documentation/filesystems/squashfs.txt (first 
I've heard pseudo, it's usually called "synthetic", ala 
https://landley.net/toybox/doc/mount.html unless you have a reference I 
don't?)

But then I was briefly the linux kernel's Documentation maintainer in a 
previous life so I may be biased. (Jonathan Corbet of lwn.net has that 
position now, I believe.) I did a certain amount of analysis back when 
it was my job, ala https://kernel.org/doc/ols/2008/ols2008v2-pages-7-18.pdf

The man pages present simple text output created from text input. The 
source is in a legacy typesetting format from 1971 (created for the AT&T 
patent and licensing department and aimed at a brand of daisy-wheel 
printer that no longer exists), but even 
http://www.catb.org/~esr/doclifter/doclifter.html back in 2003 could 
already migrate that to something else and people decided "nah, qwerty 
ain't so bad, better the devil you know...".

> No, it's both.  The 'man' macro package is imperative and unstructured
> rather than declarative and structured,

People were offered docbook 20 years ago. It was worse. (There's no 
docbook gui editor because it's TOO structured, in ways that are not 
easily visually represented. It's an ivory tower academic solution.)

> 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.

The man package's build scripts have produced html output for many 
years, you can do it on your laptop from a git clone.

> 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.

If I want "man insmod" I don't have to know it's in section 8. Making it 
more granular turns out to be less useful.

You're complaining about 40 year old design decisions that have 
persisted for good reason. People have been free to change it all along.

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

Either people updated the docs or they didn't. Having an active 
well-known place to go look and complain at is useful. Requiring 
somebody to read the source code and provide a copyright assignment to 
tweak documentation... well you've tried that since 1983, how did it go?

There may be some selection bias in the people who constantly read and 
edit this source code finding this source code to be the best place to 
put the docs. Learn to cook at the oven factory.

Rob

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

[G. Branden Robinson]

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

At 2025-09-30T08:23:10-0500, Rob Landley wrote:
> Either people updated the docs or they didn't. Having an active
> well-known place to go look and complain at is useful. Requiring
> somebody to read the source code and provide a copyright assignment to
                                   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> tweak documentation...  well you've tried that since 1983, how did it
> go?

Wrong since (at least) 2013 and wrong today.

https://lists.gnu.org/archive/html/gnustandards-commit/2013-10/msg00000.html

> There may be some selection bias in the people who constantly read and
> edit this source code finding this source code to be the best place to
> put the docs. Learn to cook at the oven factory.

Or play ill-informed games in a toy box.

Regards,
Branden

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

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

[Arsen Arsenović]

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

Rob Landley <rob@landley.net> writes:

> On 9/25/25 09:04, 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),
>
> It wasn't "lucky".

It was, it was obvious even in first edition Unix - I'll come back to
that.

> "Do one thing and do it well" was an explicit design decision the Bell
> Labs guys made in 1971.

Please spare me the football chants, I've heard enough them from the
likes of Bob Martin.  They lack nuance required to be useful rebuttals
or points of discussion, and in fact produce counter-effects when people
stick to them too dogmatically and fail to realize the best way to
decompose a problem.

For example, "one thing" is, for "things" that (unlike *most* coreutils;
there goes that luck again) can't be described as a mathematical
function whose definition is a few lines of formal description, can be
quite complex.

Compilers are such things - a compiler is effectively a pure
mathematical function from plain text into machine code (or a set of
diagnostics), and there are many such functions, yet compilers which "do
it well" are very complex (but made up of smaller parts, obviously -
this isn't a Unix insight, mathematicians have been decomposing problems
for thousands of years); and given the measure of "well" differs by
use-case, these obviously gain more complex interfaces also.

When documetning, these more complex interfaces ought to be decomposed
into logical units for obvious reasons.  There are also overarching
themes that aren't simply attached to a single (or handful) of bits of
the interface.

> Doug McIlroy wrote about it in 1978 in the Forward to the article on
> "The Unix TimeSharing System" in the Bell System Technical Journal in
> 1978: "do one thing and do it well" and then compose more complicated
> things from simple parts. Peter Salus reiterated it in "a quarter
> century of unix" (a book about the anniversary), and Mike Gancarz'
> book "the unix philosophy" went into this in some detail.
>
> That's why they could get away with a flat namespace and simple man
> pages and so on for decades.

The funny thing is that they couldn't (and here we come back to that).
Consider, for instance, file descriptors.

In the original Unix v1 programmers manual (or, at least, the copy I
could find), the term "file descriptor" is used 30 times, and defined
(poorly) twice.  It is obvious that "file descriptor" is a piece of
overarching context deserving of a section, but dogmatic flat
hierarchies of purpose-defined sections splits ("Commands", "System
calls", "Library calls", "Special files", ...) into a bunch of
pre-structured flat documents by name of procedure or command simply
cannot capture this.  You could produce a manpage "fildes.7", but its
name and relation to other bits of the manual are non-obvious,
especially to new readers.  It is also unfortunate that this section
presumably intended to contain such context ("miscellaneous") is *after*
the sections that use said context.  It is also unfortunate that, within
sections, pages are unordered.  There's obviously a partial reading
order between pages.

(A funny side note: subconsciously, I chose the name "fildes.7" as to
 not go over eight characters; it came to me naturally after many years
 of working with and on Unix-like systems, this archaic element simply
 lodged itself into my instincts after some time.)

Nowadays, the situation is even worse.  Consider the networking
functions.  Clearly, networking has overarching concepts, and clearly
networking-related procedures are related or supersede eachother
(gethostbyname/getservbyname vs. getaddrinfo for instance, or inet_*).
It is useful for these to be grouped together with overarching themes
explained without repetition or omission.  But that's not possible.

To clarify, I don't mean to imply that an OS-level manual should teach
the reader about basic networking concepts, but it is still useful to
briefly recap said concepts in order to clarify possibly-ambiguous
terminology and set up standards for your documentation.

Also, in my opinion, it is obvious that the term "file descriptor" is a
misnomer or misabstraction and that "descriptor" or "handle" - which are
significantly broader terms - would result in a far clearer abstraction
(where a file descriptor is one such descriptor or handle).

In my mind, this basic failure in design was a result of someone
chanting something like "everything is a file", and hence attaching a
read and write operation to all OS "objects" instead of understanding
that the filesystem hierarchy also contained within itself an "object"
hierarchy.  I have no way of knowing if my head-canon is correct,
though.

>> 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.
>
> The utility command line parameters are on the web at
> https://man7.org/linux/man-pages/man1/intro.1.html which seemed reasonably
> straightforward to me. (Over the years it's accumulated a lot of extra crap
> from optional packages, but as failure modes go it could be worse...)
>
> The kernel command line arguments are at
> https://kernel.org/doc/Documentation/admin-guide/kernel-parameters.txt and
> filesystems are at
> https://kernel.org/doc/Documentation/filesystems/squashfs.txt (first I've heard
> pseudo, it's usually called "synthetic", ala
> https://landley.net/toybox/doc/mount.html unless you have a reference I don't?)

The Linux documentation refers to pseudo filesystems.  One such example
I found by grep is in filesystems/vfs.rst:

  An individual dentry usually has a pointer to an inode.  Inodes are
  filesystem objects such as regular files, directories, FIFOs and other
  beasts.  They live either on the disc (for block device filesystems)
  or in the memory (for pseudo filesystems).  Inodes that live on the
  disc are copied into the memory when required and changes to the inode
  are written back to disc.  A single inode can be pointed to by
  multiple dentries (hard links, for example, do this).


... as does procfs(5), for instance, or filesystems(5), and, AFAIK, so
does the kernel codebase.

I'm surprised to see that the term is new to some; I don't think I've
ever heard anyone using different terminology.

> But then I was briefly the linux kernel's Documentation maintainer in
> a previous life so I may be biased. (Jonathan Corbet of lwn.net has
> that position now, I believe.) I did a certain amount of analysis back
> when it was my job, ala
> https://kernel.org/doc/ols/2008/ols2008v2-pages-7-18.pdf

I am aware of where they are.  The answer is "all over the place"
(consider, for instance, modules having their own parameters).  I've
gone searching enough times to remember the trail to the clearing
through the forest.

Of course, this is tangental to the manpage discussion; this is caused
by other forces also, such as the set of concerns usually lumped under
"operating system" in other communities being broken up between
occasionally-adverse groups.

> The man pages present simple text output created from text input. The
> source is in a legacy typesetting format from 1971 (created for the
> AT&T patent and licensing department and aimed at a brand of
> daisy-wheel printer that no longer exists), but even
> http://www.catb.org/~esr/doclifter/doclifter.html back in 2003 could
> already migrate that to something else and people decided "nah, qwerty
> ain't so bad, better the devil you know...".

>> No, it's both.  The 'man' macro package is imperative and unstructured
>> rather than declarative and structured,
>
> People were offered docbook 20 years ago. It was worse. (There's no
> docbook gui editor because it's TOO structured, in ways that are not
> easily visually represented. It's an ivory tower academic solution.)

I'm not sure why this is relevant - roff is capable of producing better
documents than manpages (for instance, The C Programming Language by
Brian Kernighan and Dennis Ritchie, was typeset with roff to my
awareness, or at least I seem to remember reading that in the preface at
some point - in any case, it was certainly used in well-written
publication rather than solely manpages, so the format is hardly
relevant), so clearly it's not an underlying limitation of the format.
And, again, there's a somewhat-better macro package for manpages also.

>> 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.
>
> The man package's build scripts have produced html output for many years, you
> can do it on your laptop from a git clone.

I don't even need a clone - the 'man' tool can produce HTML
automatically with the flip of a switch.

>> 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.
>
> If I want "man insmod" I don't have to know it's in section 8. Making it more
> granular turns out to be less useful.
>
> You're complaining about 40 year old design decisions that have persisted for
> good reason. People have been free to change it all along.

IMO, it is clear that developers, especially in the Unix sphere, are
unwilling to write documentation.  Washing machines from '80s tend to
have more comprehensive documentation than the documentation in Unix and
Unix-like systems.

I'm not surprised little mind was put towards this clear improvement.
This doesn't really support the "good reason" hypothesis.

>> This addresses half of the issue (what if the pages are old?), and still
>> leaves the fact its a separate software distribution unsolved.
>
> Either people updated the docs or they didn't. Having an active well-known
> place to go look and complain at is useful. Requiring somebody to read the
> source code and provide a copyright assignment to tweak documentation... well
> you've tried that since 1983, how did it go?

What?

If you're saying having updated docs is good, I agree; but you appear to
be lumping together a few things.

> There may be some selection bias in the people who constantly read and edit
> this source code finding this source code to be the best place to put the
> docs. Learn to cook at the oven factory.
>
> Rob

Have a lovely day.
-- 
Arsen Arsenović

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

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

[G. Branden Robinson]

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

Hi Arsen,

At 2025-09-30T21:57:00+0200, Arsen Arsenović wrote:
> In the original Unix v1 programmers manual (or, at least, the copy I
> could find),

As far as I know all copies of the First Edition manual on the Internet
descend from one scan.  They all are missing ascii(VII); presumably some
CSRC person tore that page out and taped it up next to their Teletype.

If someone locates a different scan, especially one with that man page
in it, consider the groff mailing list interested.

> (A funny side note: subconsciously, I chose the name "fildes.7" as to
> not go over eight characters; it came to me naturally after many years
> of working with and on Unix-like systems, this archaic element simply
> lodged itself into my instincts after some time.)

Eight's an odd choice for that, though.  As I understand it, the Fortran
linker that Unix originally used (C did not exist yet) had a limit of 6
characters for externally resolvable symbols, because that was all some
IBM operating system could handle.  File names (or "path name
components", if one insists) were limited to 14 characters until the
Berkeley "fast" file system.  The tuhs at tuhs dot org is a more
reliable resource than I can be here, though.

> Also, in my opinion, it is obvious that the term "file descriptor" is
> a misnomer or misabstraction and that "descriptor" or "handle" - which
> are significantly broader terms - would result in a far clearer
> abstraction (where a file descriptor is one such descriptor or
> handle).

"Handle" _is_ a better term.  So let us politely applaud Microsoft
managing to not make the wrong choice at _every_ turn.

Just most.

> In my mind, this basic failure in design was a result of someone
> chanting something like "everything is a file", and hence attaching a
> read and write operation to all OS "objects" instead of understanding
> that the filesystem hierarchy also contained within itself an "object"
> hierarchy.  I have no way of knowing if my head-canon is correct,
> though.

I don't either, but my impression is that much documentary work at the
Bell Labs CSRC was the work of exigetes attempting to divine Ken
Thompson's hermetic source code.  Thus the value of the Lions book.

> Of course, this is tangental to the manpage discussion; this is caused
> by other forces also, such as the set of concerns usually lumped under
> "operating system" in other communities being broken up between
> occasionally-adverse groups.

...an easier problem to have when said groups share the common notion
that microkernels are stupid.

(The problem with Mach, whose properties big kernel advocates ascribe
it toto to all microkernels past, present, and future, was that its
working set was too large, and created excessive cache pressure.  See
Liedtke, J., "On μ-Kernel Construction".[1])

It may also be the case that the path to "world domination" appears
easier with a big kernel than a microkernel.

> I'm not sure why this is relevant - roff is capable of producing
> better documents than manpages (for instance, The C Programming
> Language by Brian Kernighan and Dennis Ritchie, was typeset with roff
> to my awareness, or at least I seem to remember reading that in the
> preface at some point - in any case, it was certainly used in
> well-written publication rather than solely manpages, so the format is
> hardly relevant), so clearly it's not an underlying limitation of the
> format.

That's true.  Brian Kernighan uses groff to write his books these
days.[0]  Another well known and well received work written using *roff
was _Advanced Programming in the Unix Environment_ by W. Richard
Stevens.  I don't know what Rago has used to typeset the second and
third editions of that work.

> And, again, there's a somewhat-better macro package for manpages also.

mdoc has advantages and disadvantages.  The groff@gnu list archives
record some friendly sparring between Ingo Schwarze and me on the point.

> IMO, it is clear that developers, especially in the Unix sphere, are
> unwilling to write documentation.  Washing machines from '80s tend to
> have more comprehensive documentation than the documentation in Unix
> and Unix-like systems.

I think documentation quality (or existence) has rotted in both the
software and appliance/consumer electronics domains.  It used to be de
rigueur to include a complete circuit diagram for anything you could
buy that had a diode in it.  Now, almost everything is locked up,
physically and conceptually thanks to trade secrets, with "no
user-serviceable parts inside".  We are furthermore blessed with
stalwart opponents of copyleft and right-to-repair laws, doughtily
keeping their employers' 10-Q filings safe.[2]

The great thing about "intellectual property" is how its premier
application is suppressing the exercise of intellect.

Regards,
Branden

[0] I can't find my citation for this, but if I recall correctly, Arnold
    Robbins asked Brian Kernighan in email, and shared this fact,
    probably on the TUHS list.

[1] https://dl.acm.org/doi/pdf/10.1145/224056.224075

[2] Good news, though--one's firm may soon need only file such
    disclosures semi-annually rather than quarterly.  Free markets work
    better with less information.  Didn't Kenneth Arrow teach us that?

    https://corpgov.law.harvard.edu/2025/09/27/the-forecast-on-quarterly-reporting/

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

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

[Arsen Arsenović]

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

"G. Branden Robinson" <g.branden.robinson@gmail.com> writes:

>> (A funny side note: subconsciously, I chose the name "fildes.7" as to
>> not go over eight characters; it came to me naturally after many years
>> of working with and on Unix-like systems, this archaic element simply
>> lodged itself into my instincts after some time.)
>
> Eight's an odd choice for that, though.  As I understand it, the Fortran
> linker that Unix originally used (C did not exist yet) had a limit of 6
> characters for externally resolvable symbols, because that was all some
> IBM operating system could handle.  File names (or "path name
> components", if one insists) were limited to 14 characters until the
> Berkeley "fast" file system.  The tuhs at tuhs dot org is a more
> reliable resource than I can be here, though.

Heh, some confusion it seems.  No idea where I got eight from.
-- 
Arsen Arsenović

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

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

[Rob Landley]

On 9/30/25 14:57, Arsen Arsenović wrote:
> Rob Landley <rob@landley.net> writes:
>> It wasn't "lucky".
> 
> It was, it was obvious even in first edition Unix - I'll come back to
> that.

So obvious that you need to point it out 50 years later?

> When documetning, these more complex interfaces ought to be decomposed
> into logical units for obvious reasons.  There are also overarching
> themes that aren't simply attached to a single (or handful) of bits of
> the interface.

There's more than one way to explain almost anything.

> In the original Unix v1 programmers manual (or, at least, the copy I
> could find), the term "file descriptor" is used 30 times, and defined
> (poorly) twice.

And nobody ever bothered writing down what "inode" meant so I had to ask 
Dennis Ritchie.

https://lkml.iu.edu/hypermail/linux/kernel/0207.2/1182.html

The downside of documentation being written by people who already know 
the material. "Beginner's mind" is hard to recapture after the fact. (I 
say this as someone who's been trying for decades.)

> To clarify, I don't mean to imply that an OS-level manual should teach
> the reader about basic networking concepts, but it is still useful to
> briefly recap said concepts in order to clarify possibly-ambiguous
> terminology and set up standards for your documentation.

A tutorial and a reference are not the same thing. That's tech writing 101.

Half of teaching is figuring out what your audience already knows so you 
can connect to their knowledge base and fill in gaps without boring them 
to tears repeating what they already know. It's _hard_, and no canned 
source will get it right for every individual.

> Also, in my opinion, it is obvious

No comment.

Rob

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

[Arsen Arsenović]

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

Rob Landley <rob@landley.net> writes:

> On 9/30/25 14:57, Arsen Arsenović wrote:
>> Rob Landley <rob@landley.net> writes:
>>> It wasn't "lucky".
>> It was, it was obvious even in first edition Unix - I'll come back to
>> that.
>
> So obvious that you need to point it out 50 years later?

I don't know what you mean to imply here, but I doubt I'm the first.

>> When documetning, these more complex interfaces ought to be
>> decomposed into logical units for obvious reasons.  There are also
>> overarching themes that aren't simply attached to a single (or
>> handful) of bits of the interface.
>
> There's more than one way to explain almost anything.

Okay?

>> In the original Unix v1 programmers manual (or, at least, the copy I
>> could find), the term "file descriptor" is used 30 times, and defined
>> (poorly) twice.
>
> And nobody ever bothered writing down what "inode" meant so I had to
> ask Dennis Ritchie.
>
> https://lkml.iu.edu/hypermail/linux/kernel/0207.2/1182.html
>
> The downside of documentation being written by people who already know
> the material. "Beginner's mind" is hard to recapture after the
> fact. (I say this as someone who's been trying for decades.)
>
>> To clarify, I don't mean to imply that an OS-level manual should teach
>> the reader about basic networking concepts, but it is still useful to
>> briefly recap said concepts in order to clarify possibly-ambiguous
>> terminology and set up standards for your documentation.
>
> A tutorial and a reference are not the same thing. That's tech writing
> 101.
>
> Half of teaching is figuring out what your audience already knows so
> you can connect to their knowledge base and fill in gaps without
> boring them to tears repeating what they already know. It's _hard_,
> and no canned source will get it right for every individual.

Okay?  I'm not sure I understand what that has to do with the paragraph
you're responding to.

As said, 'man' pages don't have the ability to provide context *at all*,
whichever context might be necessary.

>> Also, in my opinion, it is obvious
>
> No comment.
>
> Rob

-- 
Arsen Arsenović

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

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

[G. Branden Robinson]

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

At 2025-10-02T20:46:11+0200, Arsen Arsenović wrote:
> As said, 'man' pages don't have the ability to provide context *at
> all*, whichever context might be necessary.

"At all" is too strong a qualifier, I think.

I think the ncurses main page in recent years offers the newcomer to the
library sufficient context to get them spun up on basic concepts.

https://invisible-island.net/ncurses/man/ncurses.3x.html

That said, I'm sure it could use further improvement.

Regards,
Branden

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