Why don't man pages have examples?

Question

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.

Answer 1

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

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

Answer 2

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.

Answer 3

It depends:

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

Answer 4

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: