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.

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

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

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

Solution 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:

View more solutions

Comments

[Peter - Reinstate Monica]

My guess is that they wanted to save valuable disk space, like with getting rid of the the CR. Cf. Beckett, Watt, p.8: "Much valuable space has been saved [...] by avoidance of the plethoric reflexive pronoun after say."

[Nathan Long]

One attempted workaround for this problem is tldr-pages.github.io, though I don't see why they make it easy to download everything up front for offline access.

[Motte001]

man jq has over 1000 lines of examples (on Ubuntu 16.04)

[Admin]

Lack of examples in man pages is the biggest turn off for Linux newcomers. The long-winded description of flags and options bores you to death and leaves you cold. Almost always they are as clear as mud. To add insult to injury, moderators in many forums have the habit of telling newbies to consult the man pages! In the words of the writer of xclip man pages "I hate man pages without examples!" -- a refreshing exception. I think official man pages should not be accepted unless they include plenty of examples (with caveats in necessary).

[Alen Milakovic]

"That sort of effort can be disregarded." I'm not sure what this means.

[Marius]

The documentation doesn't contribute anything useful when it's not based on experience.

[Marius]

Sure - I mentioned it because some of the examples which OP undoubtedly has in mind fall into this category (I'll refrain from providing a list on this forum).

[Kusalananda]

That last sentence highlights a problem with having examples in manuals. One takes the examples that best fits one's needs without fully understanding the implications of the particular application of the tool. And later, one can just say "I did it like this", but not really why or what it meant.

[Baard Kopperud]

@Kusalananda In my defense, I have read about the various options and about the sub-commands I've actually needed - just not the whole thing (yet). It's simply not relevant for my use... Despite the danger of misuse, examples do serve a purpose - and if all you need is just the most basic usage of a command, reading about all the bells and whistles are hardly necessary.

[chiggsy]

@ThomasDickey. I completely disagree with this assessment. The ability to write a utility does not necessarily come with the ability to explain the API to an end user. T

[user121391]

@Kusalananda It might also depend on the commands. Most Unix and GNU utils I know are well documented, but you need the documentation to do anything sensible. The newer Solaris commands (especially zfs) are designed pretty naturally. For example, zfs destroy pool/filesystem is basic usage and fine for 90% of use cases. Short options like -r for recursive are more special and need consultation before use, because they might have unintended side-effects.

[tgm1024--Monica was mistreated]

rsync is a very oddball manpage using a kind of first person informal dialogue. For example: Here are some examples of how I use rsync. To backup my wife’s home directory, which consists of large MS Word files and mail folders, I use a cron job that runs(...) Perhaps that should be the model.