Racing Turtles

What Linux Should Learn from BSD

Linux is great, but its man pages don't include examples, unlike BSD.



The free and open source software (FOSS) ecosystem empowers users and developers by granting them the freedom to do what they want with the software. The Linux and BSD kernels form the foundation of much of the world's free and open source software. Unfortunately, much of the world's FOSS programs are difficult to use, especially the system tools only usable in the terminal. Manual pages or man pages help bring the power of command line system tools to users by documenting their functionality.

Accessible with the "man" command, these detailed pages explain every option, argument, and command format the user will need to interact with the kernel from the command line. In Linux distributions, as in BSD, man pages exist for every system command. They contain various sections with the "NAME" of the command, a "SYNOPSIS" or summary of the command's functionality, and a "DECRIPTION" or list of all the possible options and arguments that can be passed into the command. In BSD distributions however, man pages contain an "EXAMPLES" section that makes it easier for users to understand how to use a command.

The FreeBSD man page for mkdir, for example, lists a guide to create a directory, set its file mode, and creating any parent directories as needed. The Linux man page doesn't include any common use case information. Readers need to look up common use cases on the internet to know how the mkdir command is used in daily life. How to create a directory, set its permissions, and create any necessary parent directories at the same time isn't listed in the Linux man page. Irredeemable.

The FreeBSD man page for dd provides users a clarified description of the utility, while the Linux man page doesn't. Without much introduction, readers of the Linux man page might not understand what the dd utility does, while FreeBSD man page readers understand what dd does and ow to use the command. Use cases listed in the FreeBSD man page include how to check if a disk drive has no bad blocks, how to remove a parity bit from a file, and how to check for parity errors on a file. None exist in the Linux man pages.

Computers don't read manual pages. People do. System tool manual page authors shouldn't write user manuals like reference manuals. Man pages should help people who want to make a directory, for example, by telling them how to make a directory named "foo" for example. No one should need to look up "how to make a directory" to learn when every option available is documented. The man pages exist for a reason, and the authors of the Linux system tools man pages should take inspiration from their BSD peers to improve the Linux experience.

Special Thanks #

License #

This work is licensed under CC BY-ND 4.0.