Skip to contentSkip to conversation

Hand-written manual pages for GNU coreutils

DISCUSSION Alejandro Colomar 4 participants 7 messages Jul 18 – Jul 19 Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore
Share & tools
lore

Alejandro Colomar

author maintainer
#0 lore raw

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

Signature · 1 line
<https://www.alejandro-colomar.es>
author maintainer
#1 lore raw

ls/dir/vdir(1)

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

Signature · 1 line
<https://www.alejandro-colomar.es>
#2 lore raw

Re: ls/dir/vdir(1)

Hi Alejandro,

Quoted 3 lines · On Sat, 18 Jul 2026 17:42:24 +0200 Alejandro Colomar <[email protected]> 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.

#3 lore raw

Re: ls/dir/vdir(1)

In reply to Alejandro Colomar
Quoted 8 lines · Alejandro Colomar

[[PGP Signed Part:No public key for EB89995CC290C2A9 created at 2026-07-18T17:42:18+0200 using RSA]] 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?

Quoting the documentation:

Quoted 17 lines

10.2 ‘dir’: Briefly list directory contents
===========================================

‘dir’ is equivalent to ‘ls -C -b’; that is, by default files are listed in columns, sorted vertically, and special characters are represented by backslash escape sequences.

*Note ‘ls’: ls invocation.

10.3 ‘vdir’: Verbosely list directory contents
==============================================

‘vdir’ is equivalent to ‘ls -l -b’; that is, by default files are listed in long format and special characters are represented by backslash escape sequences.

*Note ‘ls’: ls invocation.

Signature · 1 line
Arsen Arsenović
author maintainer
#4 lore raw

Re: ls/dir/vdir(1)

Hi Arsen,

Quoted 5 lines · Arsen Arsenović
Quoted 3 lines · Alejandro Colomar

[[PGP Signed Part:No public key for EB89995CC290C2A9 created at 2026-07-18T17:42:18+0200 using RSA]] Hi,

Quoted 26 lines
Quoted 5 lines

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?

Quoting the documentation:

Quoted 17 lines

10.2 ‘dir’: Briefly list directory contents
===========================================

‘dir’ is equivalent to ‘ls -C -b’; that is, by default files are listed in columns, sorted vertically, and special characters are represented by backslash escape sequences.

*Note ‘ls’: ls invocation.

10.3 ‘vdir’: Verbosely list directory contents
==============================================

‘vdir’ is equivalent to ‘ls -l -b’; that is, by default files are listed in long format and special characters are represented by backslash escape sequences.

*Note ‘ls’: ls invocation.

Thanks! I've changed the descriptions of these two programs to the following short and simple descriptions:

DESCRIPTION
vdir is equivalent to ls -l -b.

DESCRIPTION
dir is equivalent to ls -C -b.

Have a lovely day!
Alex

Signature · 1 line
<https://www.alejandro-colomar.es>
#5 lore raw
In reply to Alejandro Colomar
Quoted 10 lines · Alejandro Colomar

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

author maintainer
#6 lore raw

Hi Pádraig,

Quoted 10 lines · Pádraig Brady
Quoted 9 lines · Alejandro Colomar

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>

Quoted 7 lines
Quoted 1 line

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

Quoted 5 lines

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

Quoted 2 lines

cheers,
Padraig

Signature · 1 line
<https://www.alejandro-colomar.es>