RTFM - Read the Fine Manual

The Keys to the Kingdom
What is your reward for all this effort?
The Sequence: Just what does RTFM mean these days?

The Keys to the Kingdom

Having someone tell you to RTFM! may seem insensitive. What's worse, actually reading (heck, sometimes just finding) the manual may seem overwhelming, if not impossible.

In fact, they have just handed you the keys to the kingdom. The secret handshake. The magical knowledge that all true uber-geeks know: the one and only path to where we play is through the manuals.

The good news is that we weren't born knowing how to read the things either! There's an art to reading them, just like there's an art to writing them.

First step: pay attention!
- You were told to RtFM, not to read a book, or take a class, or even to read a fine manual. The phrase is read the fine manual. Wait, you say - is there some ultimate manual to the geek universe that these folks have in mind? (What a disturbing thought - one could argue that the info browser is exactly that. Shudder. Ok, we'll need to add stuff about the info browser to this discussion... For now, though...) There is, in fact, a very specific set/sequence that is the FM. (Hey! It intersects at the info browser, too. Stop that!)
Each time you find that you need to RtFM, keep going past the information that you were seeking (these are not the droids you were looking for.) Depending on how long you have and how much energy you have, that might be five minutes or five hours. My usual line (and practice) is to keep going until one's eyes cross and the page reads "bleepdety-bleep-bleep-bleep." And, yes, I still hit that experience myself, usual with regards to TCP/IP info (just not my thing.)
Try to take notes about / journal about / blog about your explorations. In time you'll even get to the point that you can come back and turn your notes into something useful, but even if you don't, the writing part is highly useful.

Try the steps discussed below in the sequence discussed. The sequence is an exemplar, so, for instance, if you were trying to:

solve a PerL problem	1. start with `perldoc` instead of man
	2. fall back to the perl community resources
	3. then back to O'Reilly books
solve an RisCool problem	1. start with R's own help system
	2. fall back to CRAN
	3. then back to books by R community authors

What is your reward for all this effort?

Short-term
- Faster turn-around time in finding answers to your questions, as you develop a map of the systems information out there that is structured around your interests and needs rather than some textbook author's interests
- Better problem-solving skills, too, if you journal about your experiences. To turbo-charge this change, poke around MutualDiscovery project materials.
Longer-term
- That map we discussed above is the first component of something called a knowledge scaffold. If you get serious about the writing, too, you'll find yourself wending your way into the land o' the geeks (hey, you didn't think I do all this writing for my health, did you ;-), because you'll find yourself collaboratively constructing new information tools and structures with the rest of us.
- Then, of course, you'll find that you are Writing the Fine Manuals, not just reading them... ROFL!

-- HilaryHolz - 17 Mar 2009

The Sequence: Just what does RTFM mean these days?

The section on reading man pages was written by an Ahat lab grad student, RobertSajan. Looking over what he wrote, I thought he did a terrific job, and just left it alone. Great job, Rob!

1. `man` Pages & How to Read Them

A great resource at your disposal are man pages. If you are using a command and you aren't quite sure how to use it, refer to your locally stored man pages! It can be the fastest way to get an answer to your quandary. man pages may also have info on system calls (i.e. fork, open, close, etc.), C library functions (i.e. sprintf, atoi, etc.), etc.

To access a man page for a particular command, at the terminal simply type:

man <command>

man pages are organized into about 8 sections (may slightly differ from one distribution to another):

1	User Commands
2	System Calls
3	C Library Functions
4	Devices and Special Files
5	File Formats and Conventions
6	Games et. al.
7	Miscellanea
8	System Administration tools and Deamons

Most arguments you will probably pass to man are in section 1. However, there is a large amount of information stored in the man repository. On our machine it is located in /usr/share/man/. You can check the path to a particular man page by using the -w option:

user@dayz ~]$ man -w man
/usr/share/man/en/man1/man.1.gz

Here we received the path for the man page on man. With this path you can begin to explore the available files.(1) Visit the System Call section in the man2 directory. Or perhaps today you are in the mood for some File Formats and Conventions? That'll be directory man5. There should be at least 8 sections to choose from, and various language translations as well. Go and explore your repository now, and try to browse at least briefly in each section.

Let's take a look at a simple man page for the command whoami. Typing man whoami at the command line produces the following output:

WHOAMI(1)                        User Commands                       WHOAMI(1)

NAME
       whoami - print effective userid

SYNOPSIS
       whoami [OPTION]...

DESCRIPTION
       Print the user name associated with the current effective user ID.  Same as id -un.

       --help display this help and exit

       --version
              output version information and exit

AUTHOR
       Written by Richard Mlynarik.

REPORTING BUGS
       Report bugs to <bug-coreutils@gnu.org>.

COPYRIGHT
       Copyright  �  2008  Free  Software Foundation, Inc.  License GPLv3+: GNU GPL version 3 or later
       <http://gnu.org/licenses/gpl.html>
       This is free software: you are free to change and redistribute it.  There is  NO  WARRANTY,  to
       the extent permitted by law.

SEE ALSO
       The  full  documentation  for whoami is maintained as a Texinfo manual.  If the info and whoami
       programs are properly installed at your site, the command

              info whoami

       should give you access to the complete manual.

GNU coreutils 6.10               October 2008                        WHOAMI(1)
(END)

The first line tells us that whoami is in section 1, User Commands.

WHOAMI(1)                        User Commands                       WHOAMI(1)

Note that certain commands may share the same name with perhaps system calls, or C library functions. So this line can be very useful in those circumstances.

The NAME section provides the name of the command and a very concise description.

NAME
       whoami - print effective userid

The SYNOPSIS section provides some very useful information, and it is well worth getting used to reading this line. It tells what options are available, and what argument we may or must provide. Here we are informed that whoami has some optional options.

SYNOPSIS
       whoami [OPTION]...

The DESCRIPTION section provides more detailed descriptions of the command as well as available options. Here we see that there are two options available, namely --help and --version. Note that in some man pages options may be listed in their own OPTIONS section.

DESCRIPTION
       Print the user name associated with the current effective user ID.  Same as id -un.

       --help display this help and exit

       --version
              output version information and exit

From SYNOPSIS we know where the options can be placed, and from DESCRIPTION we know that --version is valid option which we could apply as follows:

[user@dayz ~]$ whoami --version
whoami (GNU coreutils) 6.10
Copyright (C) 2008 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

Written by Richard Mlynarik.

man pages at first glance may seem overwhelming but they always (we hope) follow a standard form. This should help you quickly scan for the information you need. If you are already somewhat familiar with a command, often the SYNOPSIS, DESCRIPTION, and OPTIONS sections will be your main destinations.

The example given above was for a very short man page. In longer man pages, it may take a while to find what you are looking for, unless you use some useful navigation and searching short cuts:

`q`	quit, exit
`/`	search - enter what you want to search for after the '/' and press 'n' to navigate through the results
`ctrl` + `v`	scroll down one page
`esc v`	scroll up one page
`esc shift` + `>`	go the end of the document
`esc shift` + `<`	go to the beginning of the document

Try out your new navigation skills on man mount. Can you find the word magic? Now go back to the top. Notice that the man page for mount is in section 8. Take a moment to appreciate the SYNOPSIS section. Can you tell what is optional and what isn't? Now search for SEE ALSO. Notice that there is a mount(2) entry. This signifies that there is another man page that shares the mount name, however it is in section 2 (i.e. System Calls) instead of section 8. Quit out of the man page. And type:

man 2 mount

Now you should be looking at the mount system call information. Notice how the SYNOPSIS section has changed.

If you are curious how many man pages may exist for mount try:

whatis mount

As you've seen now, there are a lot of man pages. Sometimes you may not remember the name of a particular command. You can use apropos to help you. For example, let's say you want to use the command to print a calendar, but you just can't remember the name of that command. Hmmm... what was that command name?:

[user@dayz ~]$ apropos calendar
Date::Calc           (3pm)  - Gregorian calendar date calculations
Date::Calendar       (3pm)  - Calendar objects for different holiday schemes
Date::Calendar::Profiles (3pm)  - Some sample profiles for Date::Calendar and Date::Calendar::Year
Date::Calendar::Year (3pm)  - Implements embedded year objects for Date::Calendar
HTML::CalendarMonthSimple (3pm)  - Perl Module for Generating HTML Calendars
Time::JulianDay []   (3)  - - Julian calendar manipulations
cal []               (1)  - displays a calendar
cal []               (1p)  - print a calendar
difftime []          (3p)  - compute the difference between two calendar time values

Aha! In the above output we can see that the command cal is what we were looking for. apropos provides short descriptions of each command, functions, etc. that are in the whatis database. Your system output may differ from ours, but we also have a few perl modules listed such as Date::Calc. So apropos is useful not only for systems administration but also programming and development.

The following table summarizes the commands we've explored here that are helpful with reading and finding man pages:

`man`	`man` page reader	useful to read `man` pages
`whatis`	searches names that match the one you provide	useful when you want to see how many `man` pages exist for the same name
`apropos`	searches the whatis database of `man` page short descriptions for a match	useful when you're not quite sure of the `man` page you are looking for, but have some search term related to your problem

2. Unix Distribution Documentation

If you are running on some flavor of Unix, a great source of information on your system is the main project website for your distribution.

For example, since Fedora is the FOSS version of RedHat, we consult both http://docs.fedoraproject.org/ and https://www.redhat.com/. The installation docs will help you install your system, but they will also familiarize you with important areas, including

networking,
hard disk partitioning,
the boot loader, and much more.

You can improve your systems design, management, and administration skills by reading the excellent RHEL4 Systems Admin Guide.

Other sources will also have distribution-specific 'best-practices' and/or community consensus driven benchmarks that you can consult to significantly improve your skills, such as the Center for Information Security benchmarks.

3. Linux Documentation and Books

There are a lot of good books (and some not so good books) available on UNIX and Linux. There are even distribution specific books for Fedora, Ubuntu, etc. Here are some we like:

Fedora Linux Toolbox by Christopher Negus, Francois Caen. 2008, Wiley Publishing; ISBN: 978-0-470-08291-1
- excellent compact reference book - read and explore a section a week and you will gain skills quickly
LinuxTools also available for Ubuntu, SUSE & BSD flavors (Mac OS X April 2009)
Unix Power Tools By Shelley Powers, Jerry Peek, Tim O'Reilly, Mike Loukides; ISBN 0-596-00330-7
- This book helps increase your productivity once you've learned the basic commands. For example it includes 30 pages on sed and 12 pages on awk.

These are just a few. There are a lot of great linux books out there. Two publishing houses (although not the only ones) that regularly produce high quality work are O'Reilly and New Riders books. O'Reilly and New Riders books use authors who are also significant contributors to the software/platform/etc. in question, so in a sense their books are an extension of the RtFM practice.

[see also ManagingUnix]

Notes

1 : We assume the other man files are probably somewhere along the same path, and they probably are. You can also run whereis man to find more man directories and places to look. Let us know if you have trouble finding them.