man woman

No manual entry for woman

Oooh, I just know I'm going to hear it in the comments for that one. But you know what? Just how many of you have tried something similar with other words? You know you have at least once or twice. Go ahead, try one or two..you might be surprised. So why an article on man pages? Well, it's not just man pages, it's more like how to get information from Linux. Sure, you can use the internet and search for your problem, but you can also use the tried and true manual pages (or info) that comes with Linux distros out there. This and my next blog post aim to cover both Man pages and Info pages. Not only will you learn a thing or two about each one "- and, probably more than you ever wanted to know about each -" but the differences between the two as well. Granted if you just want basic syntax information about a command, there is always the tried and true: --help, -h or -?.

So just why would you use Man and Info over using your internet browser? Well, for some of us out there, servers are console only and can also have restricted (depending on your infrastructure) internet access. Being able to reference a Man or Info page straight from a console is a very quick and easy way to pull up information on a command-line argument, or what a specific command does, or what's in a configuration file. The argument could be made that there are websites that replicate Man pages, with hyper links to other Man pages. But are they the correct pages for your distro and version? The best way, in my opinion, is to use the pages that were installed with the packages that you are currently using with your distribution. Keep in mind though, the Man utility might not have been installed with your various flavor of Linux at the time you installed it. But most supported Linux distributions that I have come across in the wild do contain Man packages that can be installed (man-db and manpages come to mind for the necessary packages for Debian based systems).

Now what's this about Man and Info? I'll step up on my soapbox here for a second, and once again I'm sure to see a comment (or 10) about how one is better than the other. Personally I have always preferred Man pages, they have been around since as long as I've been messing around with Unix and Linux (90's) and of course around much longer than that. Info was created by the FSF (Free Software Foundation) as a hypertext document with more in-depth information than you will find in Man pages. Why two of them you ask? I have no clue, you would have to ask the FSF about that. It can be really confusing when you 'man sed' and read the short information stored in sed's Man page, then 'info sed' and find a lot more information stored in the Info pages. I found that Gnu utilities have very in-depth Info pages, but other command line utilities are just Man pages read into Info. If I need further information than what my Man page tells me, then I'll see if Info has it. In a nutshell though, the purpose of either utility is to make it easier for the end user to get information from Linux.

Because there is so much information out there in Man pages and Info, and such little space in a blog post, I will be splitting these up into two parts. Part one will be on Man pages and the second part will be on Info.

Man Pages

As I said earlier, Man pages have been around for quite a while. They were designed as a way for people to reference help (manual) pages on a system. A programmer/engineer/etc who created a utility was (and still is) expected to create a Man page that follows a certain page layout so that others can reference relevant information about the topic at hand. This is just my 2c, but I don't believe that because Info is around, Man pages are going to go away. They have become the heart and soul of the Linux/Unix infrastructure when it comes to referencing utility information. With that being said, let's get our learn on.

Man Page Layout and Navigation

What I do like about Man pages is that most of the time they're laid out the same. Call it military discipline, or a touch of OCD, whatever you prefer. I say most of the time because there are the select few that will change around one or two things in the order but they usually have the 9 main topics in the Man page. This is how they break down:

Name

- This is the name of the subject of the page..usually has a number in parentheses that denote the manual section. That number relates to the these sections:
Man Page Sections

1. User Commands
2. System Calls
3. Library Calls
4. Special Files
5. File Formats
6. Games
7. Miscellaneous
8. System Administration
9. Kernel Routines

Synopsis

- A brief summary of the subject of the documentation

Description

- Self explanatory, more in-depth description of the subject and what it does

Options

- Explanation of execution options, command line arguments and what each one does

Files

- This section lists various files that relate to the topic, such as configuration files

Environment

- Environmental variables that affect the program, function, file, etc

Bugs

- Known bugs

See Also

- This is very useful section. This will reference related Man pages.

Author (or History)

- Who wrote it, and/or who contributed to it.

Navigation

The Man utility uses Less to display help pages. What this means is if you're familiar with Less, you shouldn't have a problem with Man. For those of you that are not familiar with Less, or its better known cousin More, than here is your quick crash course in Man page navigation. Once you open up a Man page, you can navigate up/down a single line with either the up/down key or press <enter> to go down 1 Line. To go Up/Down an entire page you can use the PgUp/PgDn Keys, Space Bar, or D Key for Down (B Key for Up). If you are looking for a specific word or phrase in the Man page, type '/' and enter your phrase to search the Man page. The letter 'n' will search for the next word in that phrase. The '/' character will also search the page for the last previously searched phrase. And there you have it, basic navigation. I've provided a quick cheat sheet below.

*Navigation - Usually uses Less
Up/Down- Up & Down Keys.
Page Up & Down - PgUp/PgDn Keys
Search - '/foo'
Search Next - '/' or N key
Summary of Commands (help) - h key
Quit - q key
Down 1 Screen - Spacebar or D key
Up 1 Screen - B key
Down 1 line - Enter Tips and Tricks

Here are some basic tips and tricks for using Man pages, from searching Man pages to printing Man pages and everything in-between. Don't feel bad if you get lost, there's a manpage for Man!

Search

Have you ever had that problem where you just know there's a manpage for a certain keyword but you can't remember the manpage itself? By using man -k <keyword> Man will search through its list of manpages for that specific keyword and list all manpages that reference it. For example:

man -k sleep

apmsleep (1)         - go into suspend or standby mode and wake-up later
clock_nanosleep (2)  - high-resolution sleep with specifiable clock
nanosleep(2)         - high-resolution sleep 
rtcwake (8)          - enter a system sleep state until specified wakeup time 
sleep (1)            - delay for a specified amount of time 
sleep (3)            - Sleep for the specified number of seconds 
usleep (3)           - suspend execution for microsecond intervals 

From here I can see all the manpages with the word 'sleep' in them. Earlier in this article I described the various sections of the man database, the results for -k shows those section numbers. Because of this, we know that there are two sleep pages, one that is a user command and another that is a library call. By just typing 'man sleep' odds are you will end up with the user commands when you really wanted the library calls. By knowing the correction section, you can now type: man 3 sleep and pull up the manual page for the sleep() library call. On the same token, if you know the command you are looking for but feel that there are more than one Man page for the command, use the -f flag: man -f <command> will list the command with the sections in parenthesis. As stated earlier, typing man section <command> will bring you to the specific section you want to reference. Printing and Display

So what do you do if you want to print the Man page for reference? And just who does that? Well, I frequently print off Man pages and reference them from time to time when I am not near a terminal, maybe that's the techie in me (or the blogger). I tend to print off the Man pages that I need when I'm writing articles so that I have them close at hand, especially if I know that I'll be 'offline'. Here are 3 ways to send your Man pages to something other than your computer terminal.

# Send sleep manpage to default printer
man sleep | col -b | lpr

# Send sleep manpage to ps2pdf utility (must have installed) and save as sleep.pdf
man -t sleep | ps2pdf - sleep.pdf

# dump the sleep Man page to a text file
man sleep | col -b > sleep.txt

What if you have a command that could be either a user command or a library call but you want to see both of them? You're lazy (like me) and don't want to type: man 1 sleep, man 3 sleep but want to see one after the other? By typing man -a <command> the Man utility will display the command in succession. Once the first one is complete it will go to the next man page.

One last tip before we head off to Info, the one I love showing off to my minions from time to time...this one needs no explanation so I'll leave it to your imagination:

man hier

Part II of 'Getting help from linux' will cover Info. Stay Tuned!