How to Read a Linux Manual Page

Linux manual pages are evidently impenetrable walls of text for some people.

 As such, I've compiled a short list of "hacks" that can help you as you try to learn a new Linux tool. The manual pages are immensely helpful, if you manage do penetrate them and understand them.

Hack #1: Read the manpage backwards.

Well, almost.  Skip down to the end, look around, and THEN start at the beginning.

Often, the "SEE ALSO" section and the "EXAMPLES" section, which are both near the end, will give you what you need - either another program to look at, or the options you need for common scenarios they've documented as examples.  Sometimes there's a separate manpage for a programs configuration files, and if that's what you're looking for, you won't find it on the current manpage.  So, start at the end.

Hack #2: Read the manpage twice. Or, thrice. Or, more.

I've found that I learn more about a command every time I read the manual page. This remains true of programs I've been using FOR THREE DECADES, having read their manpages many times over the years.

Hack #3: Understand every sentence.

Manual pages are incredibly dense. They're packed solid with important information. A particular sentence might seem obvious. If you think it is obvious, and might not even need to be mentioned... dig deeper, because there's DEFINITELY a reason the author wrote that sentence.

It wasn't frivolous or redundant. If you have questions about what a sentence is trying to convey, don't hesitate to ask people. It's better to be known as being curious and inquisitive than to have walked right past an important clue.

Here's an example - the very first line of the Bash manual: "Bash is an sh-compatible command language interpreter that executes commands read from the standard input or from a file."

So that means two different ways it'll read commands, right? Wrong! At least four:

• from the terminal as stdin
• from a file as stdin: bash < somefile.of.commands
• from a file given as an argument - bash somefile.of.commands
• from a shellscript - a file that starts with a line that says "#!/bin/bash" and has +x permissions

The distinction on some of the above might seem unnecessary - but knowledge is power.  I've run into cases were I've been able to run a shell script which broke for everyone else just by firing it up a particular way.

Hack #4: Speak the lingo.

Options.  Parameters.  Arguments.  Shell variables v. Environment variables v. Config file settings.   Globs vs. Regex vs. Extended regex.  File types v. File extensions. (totally different things!)  Services v. Daemons v.  Processes.  Filenames v. Paths. Relative paths v. Full paths.

All of those things are different - know the differences and don't get confused between them.

If a manpage author is using a different name for some things, almost certainly, those things aren't the same as some other things you're accustomed to.  So, investigate and find out, what's the difference?

Hack #5: think outside the box.

In other words, don't limit your learning about a program to just the man pages. Specifically, (a) don't hesitate to review the source code (b) don't hesitate to google a particular command, along with some keywords regarding your usage scenario ("vi xml file" for example) and (c) don't hesitate to ask colleagues about how they use a particular program.

Also - use the program apropos to find interesting manpages.  It's "google for your manpages".

Hack #6: welcome feedback.

If you have other manpage reading hacks which I haven't mentioned - by all means, leave a comment with details!  I'll be happy to extend this post to include other techniques which I missed.