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. HEAD -------------------- Print first 10 lines of `file.txt`: head file.txt Print first 40 lines of `file.txt`: head -n 40 file.txt 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 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 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/
examples.patch
Description: Binary data
