Hand-written manual pages for GNU coreutils

Hand-written manual pages for GNU coreutils

[Alejandro Colomar]

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

Hi!

I've started working on improving the quality of the manual pages for
coreutils, as I promised some time ago I'd do.  The work is --for the
moment-- in the 'coreutils' branch of the Linux man-pages repo.  Once
I finish, they won't be auto-generated from --help anymore.

<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/log/?h=coreutils>

We'll talk about incorporation to the coreutils.git repo later.


Have a lovely day!
Alex

-- 
<https://www.alejandro-colomar.es>

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

ls/dir/vdir(1)

[Alejandro Colomar]

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

Hi,

I have some doubts about specific pages; let's start with ls/dir/vdir.

Experimentally, ls(1) and dir(1) seem to be exactly the same.  I'd like
to document dir(1) with a short page saying that it's equivalent to
ls(1).  Is this correct, or is there any subtle difference?

vdir(1) seems to be `ls -l`.  Is this also correct?  Or is there any
other subtle difference?


Are there any other coreutils commands that are similarly equivalent and
whose page could be similarly simplified?


Have a lovely day!
Alex

-- 
<https://www.alejandro-colomar.es>

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

Re: ls/dir/vdir(1)

[Ivan Sokolov]

Hi Alejandro,

On Sat, 18 Jul 2026 17:42:24 +0200
Alejandro Colomar <alx@kernel.org> wrote:

> Experimentally, ls(1) and dir(1) seem to be exactly the same.  I'd
> like to document dir(1) with a short page saying that it's equivalent
> to ls(1).  Is this correct, or is there any subtle difference?

From https://www.gnu.org/prep/standards/standards.html#User-Interfaces :

  For example, we provide a dir program much like ls except that its
  default output format is always multi-column format.

That's where I learnt about `dir`, but similar is said in `info dir`.
You can confirm this by comparing the output of `dir|cat` vs `ls|cat`.

I think to know these kinds of differences you'd need to refer to GNU
texinfo pages (short of just reading the source). After all, the GNU
project treats them as the primary documentation.

Re: Hand-written manual pages for GNU coreutils

[Pádraig Brady]

On 18/07/2026 16:13, Alejandro Colomar wrote:
> Hi!
> 
> I've started working on improving the quality of the manual pages for
> coreutils, as I promised some time ago I'd do.  The work is --for the
> moment-- in the 'coreutils' branch of the Linux man-pages repo.  Once
> I finish, they won't be auto-generated from --help anymore.
> 
> <https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/log/?h=coreutils>
> 
> We'll talk about incorporation to the coreutils.git repo later.

For reference, it was previously discussed at:https://lists.gnu.org/archive/html/coreutils/2025-09/msg00151.html
For clarifications on any details, please see the full documentation
for any command at the link at the bottom of the coreutils man page.

E.g. `man vdir` references https://www.gnu.org/software/coreutils/vdir

Also note that since v9.10 each coreutils man page has deep links
from each option in the man page to the corresponding description
in the full documentation.  That is something that could be maintained
in any forked man pages.

cheers,
Padraig

Re: Hand-written manual pages for GNU coreutils

[Alejandro Colomar]

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

Hi Pádraig,

On 2026-07-18T18:02:43+0100, Pádraig Brady wrote:
> On 18/07/2026 16:13, Alejandro Colomar wrote:
> > Hi!
> > 
> > I've started working on improving the quality of the manual pages for
> > coreutils, as I promised some time ago I'd do.  The work is --for the
> > moment-- in the 'coreutils' branch of the Linux man-pages repo.  Once
> > I finish, they won't be auto-generated from --help anymore.
> > 
> > <https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/log/?h=coreutils>
> > 
> > We'll talk about incorporation to the coreutils.git repo later.
> 
> For reference, it was previously discussed at:https://lists.gnu.org/archive/html/coreutils/2025-09/msg00151.html
> For clarifications on any details, please see the full documentation
> for any command at the link at the bottom of the coreutils man page.
> 
> E.g. `man vdir` references https://www.gnu.org/software/coreutils/vdir

The link doesn't work for me at the moment, but I've found the
differences between ls/dir/vdir here:
<https://unix.stackexchange.com/a/344222/341413>.

> 
> Also note that since v9.10 each coreutils man page has deep links
> from each option in the man page to the corresponding description
> in the full documentation.  That is something that could be maintained
> in any forked man pages.

Yup, I noticed that a moment ago.  I'll keep those links.  :)

I've done the initial import with this:

            $ dpkg -l coreutils \
                    | tail -n1;
            ii  coreutils      9.10-1devuan1 amd64        GNU core utilities
            $ apt-file show coreutils \
                    | grep man1/ \
                    | cut -f2 -d' ' \
                    | xargs -I{} find {} -type f
                    | xargs cp -t man1/;
            $ apt-file show coreutils \
                    | grep man8/ \
                    | cut -f2 -d' ' \
                    | xargs -I{} find {} -type f
                    | xargs cp -t man8/;
            $ find man -type f \
                    | grep '\.gz$' \
                    | xargs gunzip;

It's 9.10, so I guess it has everything.  If there's any page that is
not available in Devuan, or there's any change in git that you haven't
released yet and want to include, just let me know.


Have a lovely day!
Alex

> cheers,
> Padraig

-- 
<https://www.alejandro-colomar.es>

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