On 23/02/2026 20:48, Julia Evans wrote:
Hello!
I work on helping users understand how to use command line tools,
and I've heard from many users over the years that they find the GNU
coreutils man pages difficult to use because of the lack of examples.
I'm aware that the info manual is the primary coreutils documentation,
but I've heard from many many Linux users over the years that they're
unaware that the info manual exists or that they find the `info` tool hard to
use, and that instead they prefer to use the man pages even if they don't
contain as much information as the info docs.
This is especially hard for infrequent command line users, who likely
won't know or remember that there are multiple documentation tools on
their system.
I searched the mailing list archives to learn about why
the coreutils man pages do not have examples, and saw here
https://lists.gnu.org/archive/html/coreutils/2017-03/msg00042.html that
one difficulty is keeping two sets of documentation in sync.
I want to propose a idea to help infrequent coreutils users quickly
get basic examples using `man`, without introducing too much extra
maintenance burden on the coreutils maintainers.
The idea is to add a small number of extremely basic examples to the
`man/{tool}.x` files, which are so basic that they're unlikely to be
updated very often in the future. I've attached a patch to explain what
I mean. I noticed that there are already a couple of examples in those
files (for `stdbuf` and `od`) so hopefully other examples could fit in with
those.
The way I'm thinking about this is the man page examples could be more
of a "quick reference" for users who just want to remember how to use
the tool at a very basic level, and users would refer to the info
manual if they have a more detailed question.
I've attached examples for a few tools as a patch. Please let me know if
this has been proposed before and rejected, I'm very open to feedback.
Thanks for reading, I'm a long time coreutils fan (I've used them most
days since I was a teenager struggling to install Debian Sarge) and I'd
love to see them continue to become more accessible to everyone.
best,
Julia
-----------
Here's a plain text version of the examples in the patch if you (like
me) don't want to read raw roff. I actually wrote them in Markdown and
converted them with pandoc, very happy to adjust my conversion script or
anything else.
Yes 1 or 2 examples is fine and useful.
but yes they must be very carefully considered.
HEAD
--------------------
Print first 10 lines of `file.txt`:
head file.txt
Print first 40 lines of `file.txt`:
head -n 40 file.txt
I wouldn't give two examples of essentially the same functionality.
I'd also use the example to show correct form when there are variants.
So for head we could have:
head -n 10 file.txt # first 10 lines
head -n -1 file.txt # all except last line
TAIL
--------------------
Print last 10 lines of `file.txt`:
tail file.txt
Print last 40 lines of `file.txt`:
tail -n 40 file.txt
Print new lines added to `/var/log/messages.txt` as they're added:
tail -f /var/log/messages.txt
Here I'd use:
tail -n 10 file.txt # last 10 lines
tail -n +2 file.txt # all except first line
tail -F /var/log/messages.txt # print lines as they're added
KILL
--------------------
Send a SIGTERM signal to the process with PID 1234:
kill 1234
Send a SIGKILL signal to PID 1234. The process can't block this signal,
so it will usually terminate immediately:
kill -9 1234
Send a SIGHUP signal to PID 1234:
kill -HUP 1234
Again no need for variants of same functionality. Ok to have:
kill 1234 # send SIGTERM to pid 1234
kill -HUP 1234 # send SIGHUP to pid 1234
kill -l $? # show if last command was terminated with signal
MV
--------------------
Rename `a.txt` to `b.txt`:
mv a.txt b.txt
Move `a.txt` to the directory `/home/heather`:
mv a.txt /home/heather/
Move all files ending in `.jpg` in the current directory to the `photos`
directory:
mv *.jpg ./photos/
This form may fail if there are too many jpg files,
so we should avoid examples like that.
Perhaps it's worth showing:
find . -name '*.jpg' -print0 | xargs -r0 mv -t photos/
cheers,
Padraig
