How to use a man page: Faster than a Google search

Linux manual pages are easier to use than you think and hold a wealth of information.
435 readers like this.
Why the operating system matters even more in 2017

Internet Archive Book Images. Modified by Opensource.com. CC BY-SA 4.0

It's easy to get into the habit of googling anything you want to know about a command or operation in Linux, but I'd argue there's something even better: a living and breathing, complete reference, the man pages, which is short for manual pages.

The history of man pages predates Linux, all the way back to the early days of Unix. According to Wikipedia, Dennis Ritchie and Ken Thompson wrote the first man pages in 1971, well before the days of personal computers, around the time when many calculators in use were the size of toaster ovens. Man pages also have a reputation of being terse and, in a way, have a language of their own. Just like Unix and Linux, the man pages have not been static, and they continue to be developed and maintained just like the kernel.

Man pages are divided into sections referenced by numbers:

  1. General user commands
  2. System calls
  3. Library functions
  4. Special files and drivers
  5. File formats
  6. Games and screensavers
  7. Miscellanea
  8. System administration commands and daemons

Even so, users generally don't need to know the section where a particular command lies to find what they need.

The files are formatted in a way that may look odd to many users today. Originally, they were written in in an old form of markup called troff because they were designed to be printed through a PostScript printer, so they included formatting for headers and other layout aspects. In Linux, groff is used instead.

In my Fedora, the man pages are located in /usr/share/man with subdirectories (like man1 for Section 1 commands) as well as additional subdirectories for translations of the man pages.

If you look up the man page for the command man, you'll see the file man.1.gz, which is the man pages compressed with the gzip utility. To access a man page, type a command such as:

man man

for example, to show the man page for man. This uncompresses the man page, interprets the formatting commands, and displays the results with less, so navigation is the same as when you use less.

All man pages should have the following subsections: Name, Synopsis, Description, Examples, and See Also. Many have additional sections, like Options, Exit Status, Environment, Bugs, Files, Author, Reporting Bugs, History, and Copyright.

Breaking down a man page

To explain how to interpret a typical man page, let's use the man page for ls as an example. Under Name, we see

ls - list directory contents

which tells us what ls means in the simplest terms.

Under Synopsis, we begin to see the terseness:

ls [OPTION]... [FILE]…

Any element that occurs inside brackets is optional. The above command means you can legitimately type ls and nothing else. The ellipsis after each element indicates that you can include as many options as you want (as long as they're compatible with each other) and as many files as you want. You can specify a directory name, and you can also use * as a wildcard. For example:

ls Documents/*.txt

Under Description, we see a more verbose description of what the command does, followed by a list of the available options for the command. The first option for ls is

-a, --all 
	do not ignore entries starting with .

If we want to use this option, we can either type the short form syntax, -a, or the long form --all. Not all options have two forms (e.g., --author), and even when they do, they aren't always so obviously related (e.g., -F, --classify). When you want to use multiple options, you can either type the short forms with spaces in between or type them with a single hyphen and no spaces (as long as they do not require further sub-options). Therefore,

ls -a -d -l

and

ls -adl

are equivalent.

The command tar is somewhat unique, presumably due to its long history, in that it doesn't require a hyphen at all for the short form. Therefore,

tar -cvf filearchive.tar thisdirectory/

and

tar cvf filearchive.tar thisdirectory/

are both legitimate.

On the ls man page, after Description are Author, Reporting Bugs, Copyright, and See Also.

The See Also section will often suggest related man pages, so it is generally worth a glance. After all, there is much more to man pages than just commands.

Certain commands that are specific to Bash and not system commands, like alias, cd, and a number of others, are listed together in a single BASH_BUILTINS man page. While the documentation for these is even more terse and compact, overall it contains similar information.

I find that man pages offer a lot of good, usable information, especially when I need a command I haven't used recently, and I need to brush up on the options and requirements. This is one place where the man pages' much-maligned terseness is actually very beneficial.

Tags
Greg Pittman
Greg is a retired neurologist in Louisville, Kentucky, with a long-standing interest in computers and programming, beginning with Fortran IV in the 1960s. When Linux and open source software came along, it kindled a commitment to learning more, and eventually contributing. He is a member of the Scribus Team.

11 Comments

> Originally, they were written in in an old form of markup called troff because they were designed to be printed through a PostScript printer

Ah, no, PostScript printers also did not exist when troff was invented. troff, and the language it consumes, was designed originally to drive a Graphic Systems CAT phototypesetter.

Googling comes with example, most man pages don't.

man pages are examples of how NOT to write manuals. They are one of the biggest turn-offs to using Linux. Linux needs constructive help pages.

Sounds like Google is your friend. For many commands, a more extensively written documentation would be very large.

In reply to by John5g6 (not verified)

I use man pages. Some are better than others.

A great project that I always install is the cheat command: https://github.com/chrisallenlane/cheat

It works like a man page:

$ cheat tar

Prints common examples of how the tar command gets used.

It's got a bunch of command examples, and you can add more easily, and even contribute examples back. Combined with man pages, it's a pretty complete reference set.

A well-written man page is a thing of beauty. An user doesn't need Googled examples if the man has clear, concise writing. Examples may be included in the man page if it's especially troublesome, otherwise -- but if you have to look up a Googled script-kiddie example, you're not really understanding the way the command works.

I'm surprised nobody has mentioned man2html yet ... it allows you to browse man pages in your web browser. It took a little setting up initially, but as previously mentioned here: MAN pages are a great example of how NOT to write manuals. I find man2html very useful ... I often have a web browser window open anyway, as well as a custom "home" page with various search boxes. Here I can simply type the name of the command & hit Enter to see the entire MAN page in nicely formatted & scrollable text format =)

Try to use a search engine that respects your privacy.

It has become difficult to find and install these days, but my favourite viewer for man pages was xman. Yes the athena widgets are a bit clunky and it is datet but still it offered an easy alternative to just plain shell.

Most often you don't need a Search Engine!
Just RTFM :)

Creative Commons LicenseThis work is licensed under a Creative Commons Attribution-Share Alike 4.0 International License.