Is there a reason why most man pages don't include a few common examples? They usually explain all the possible options, but that makes it even harder for a beginner to understand how it's "usually" used.
That depends on the man pages... Traditionally, they have included a section with examples - but for some reason that is usually missing from the man pages under Linux (and I assume other using GNU commands - which are most these days). On for example Solaris on the other hand, almost every man page include the Example section, often with several examples.
If I were to guess, FSF/GNU has for a long time discouraged use of
man pages and prefer users to use info for documentation instead.
info pages tend to be more comprehensive than man pages, and usually do include examples.
info pages are also more "topical" - i.e. related commands (eg. commands for finding files) can often be found together.
Another reason may be that GNU and its
man pages are used on many different operating systems which may differ from each other (there are after all lots of differences just between different Linux distros). The intention may have been that the publisher added examples relevant to the particular OS/distro - which obviously is rarely done.
I would also add that
man pages were never intended to "teach beginners". UNIX was developed by computer experts (old term "hackers") and intended to be used by computer experts. The man pages were thus not made to teach a novice, but to quickly assist a computer expert who needed a reminder for some obscure option or strange file format - and this is reflected in how a man page is sectioned.
man-pages are thus intended as
- A quick reference to refresh your memory; showing you how the command should be called, and listing available options.
- A deep and thorough - and usually very technical - description of all aspects of the command. It's written by computer experts, for fellow computer experts.
- List of environment variables and files (i.e. config files) used by the command.
- Reference to other documentation (eg. books), and other
manpages - eg. for the format of config files and related/similar commands.
That said, I very much agree with you that
man pages ought to have examples, since they can explain the usage better than wading through the man page itself. Too bad examples generally aren't available on Linux
Sample of the Example part of a Solaris man page - zfs(1M):
(...) EXAMPLES Example 1 Creating a ZFS File System Hierarchy The following commands create a filesystem named pool/home and a filesystem named pool/home/bob. The mount point /export/home is set for the parent filesystem, and is automatically inherited by the child filesystem. # zfs create pool/home # zfs set mountpoint=/export/home pool/home # zfs create pool/home/bob Example 2 Creating a ZFS Snapshot The following command creates a snapshot named yesterday. This snapshot is mounted on demand in the .zfs/snapshot directory at the root of the pool/home/bob file system. # zfs snapshot pool/home/bob@yesterday Example 3 Creating and Destroying Multiple Snapshots The following command creates snapshots named yesterday of pool/home and all of its descendent file systems. Each snapshot is mounted on demand in the .zfs/snapshot directory at the root of its file system. The second command destroys the newly created snapshots. # zfs snapshot -r pool/home@yesterday # zfs destroy -r pool/home@yesterday SunOS 5.11 Last change: 23 Jul 2012 51 System Administration Commands zfs(1M) Example 4 Disabling and Enabling File System Compression The following command disables the compression property for (...)
This particular man page comes with 16(!) such examples... Kudos to Solaris!
(And I'll admit I myself have mostly followed these examples, instead of reading the whole man page for this command...)
I don't think there's a good answer to this. It's a culture thing. Some man pages do have example usage. E.g.
man rsync. You could try to change the culture by writing to the man page author and asking him or her to add some sample usage or (much better) offering some sample usage examples yourself. If you offer a free software author a patch, particularly a documentation patch, it's approximately ten thousand times more likely to achieve the desired result than a simple request.
most of the programs that you would find interesting are developed over a period of time, initially to solve a problem and later to improve the solution. The developers of the programs explain what they thought was important to know (and documentation was not the problem they were solving).
for some programs, the developers prefer to provide sample programs or scripts which show how to use a given program (or library). Again, this is done to solve a problem: making the program easier to test.
Some of the examples may be based on bug reports from users, and when short finds a place in the manual. Lengthy examples are rarely provided in manuals, and short examples have the problem that they tend to be trivial, repetitive and not really providing the user as much insight as a well organized description of the way a program works.
in some cases you'll find documentation which is provided by others not involved in the development process. That is, the developers did not participate except for reviewing the documentation. That sort of effort can be disregarded.
If you're looking for an alternative to man pages, you could always try bro pages, which only show various examples to a command, which you can then vote on among a list of community-submitted examples. For example, the command
bro tar will give you: