HOWTO Read The Fine Manual (RTFM)

From Gentoo Linux Wiki

Introduction

Users that are new to using GNU/Linux or Gentoo will quickly hear the phrase "RTFM!" in any number of contexts when trying to seek answer to their questions. If you're one of those victims, this entry hopes to put you on the path to self-education, and how to help yourself.

The abbreviation RTFM can take many forms (mostly the 'F'), but in a nice sense, it is saying to Read The Fine Manual, or read the already provided documentation for the problem you are running into. If you hear RTFM in answer to your question, chances are that:

• Documentation has been liberally provided to avoid the trap you are in
• Many people have run into the same scenario, and the fix has been well documented
• You didn't do any research at all

Gentoo is a fine distribution to use, but you'll quickly discover that since all the options are left up to the user, documentation is a godsend once you know where to look and how to search.

So Where's the Manual?

There are a lot of places to find documenation on linux commands, kernel setups, hardware problems, and software configurations. Let's look at a few of them briefly.

MAN pages

Often times you may also hear in response to your frequently asked question, "Did you read the man?" MAN pages are accessible for a lot of commands on your system, and always a great place to start looking for instructions on how to do something.

There are a couple of ways to see what MAN pages are available on your system. One is to use apropos to search for a keyword of available MAN pages. apropos only takes keywords as an argument.

For example, if you wanted to search to see what MAN pages about NTFS support were on your system, you would run apropos ntfs.

 mkntfs               (8)  - create a NTFS 1.2 (Windows NT/2000/XP) file system
 ntfscat              (8)  - concatenate files and print them on the standard output
 ntfsclone            (8)  - Efficiently clone an NTFS filesystem
 ntfscluster          (8)  - identify files in a specified region of an NTFS volume
 ntfsfix              (8)  - tool for fixing NTFS partitions altered by the Linux kernel NTFS driver
 ntfsinfo             (8)  - dump a file's attributes
 ntfslabel            (8)  - display/change the label on an ntfs file system
 ntfsls               (8)  - list directory contents on an NTFS file system
 ntfsresize           (8)  - resize an NTFS filesystem
 ntfsundelete         (8)  - recover a deleted file from an NTFS volume

Also, here's a small tip. If apropos is too hard to remember or type, you can use man -k <keyword> instead.

Either way, man -k or apropos will return a list of available MAN pages. Then just run man <page> to see the included documentation for that program.

Another way to search the MAN pages is to use man -K to search the content. It will take a few seconds to find the files, so be patient. Once it does find some results, it will output something like this:

$ man -K ntfs
/usr/share/man/man8/ntfslabel.8.gz? [ynq]

If you hit 'y', then man will display the page. After quitting, it will resume the search.

Hit 'n' or 'Enter' to skip to the next search entry, and 'q' to quit searching.

man has a lot of keybindings you can use that makes it easy to search and navigate. See man man for instructions. :)

KDE users can use the "man:" prefix inthe "Location" bar of Konqueror to see a man page. For example, put "man:ntfsfix" in the location bar to see the man page for "ntfsfix".

INFO pages

Info pages are like the MAN pages except that most of them are written for GNU utilities. Most GNU apps will have a very short man page, and refer you to the info page instead for more details.

Just like the man command, you can view the documentation with info <page>.

Here's another tip: if you like your MAN and INFO pages nicely formed with color, emerge app-text/pinfo for an ncurses viewer of both manual formats. This tool is highly recommended for easier navigation.

Project Documentation

A lot of the projects come with documentation, either included in the package that you will download with the source code, or on their own website. This is another great 'first stop' place to look.

On a Gentoo system, the documentation is by default installed into /usr/share/doc/package-name-and-version with the files compressed with gzip to save space. In some cases, this is the only documentation that a project will provide.

Even if a file is gzipped, like README.gz, you can still read it with less.

 $ less README.gz

Or, if you like, you can use zcat, part of the gzip project, to unzip a file and display its output on the fly.

 $ zcat README.gz | less

A lot of projects will include basic help files like README, CHANGELOG, FAQ and INSTALL. They are always a great place to look.

Some projects will have even more documentation on their website, or even a wiki or project dedicated just to providing documentation! The developers get fielded a lot by the same questions, too. You can find a project's website from within portage just by searching the package name.

 $ emerge -s ntfsprogs
 ...
 Homepage:    http://linux-ntfs.sourceforge.net/

Gentoo Resources

Gentoo is renowned for its documentation. Take advantage of it! The more common your circumstance and problem, the more likely that docs already exist on how to fix or work around it.

A listing of all official Gentoo documentation is available here.

Some more common ones include:

• FAQ
• The X Server Configuration HOWTO
• Gentoo Linux ALSA Guide

Gentoo Handbook

Installing Gentoo can be frustrating, especially when things don't work correctly the first time around. Usually a lot of issues can be traced simply by not reading the very-well written Gentoo Handbook clearly and correctly.

In most cases, you will not have issues if you don't deviate from the instructions provided, and you choose the default options when multiple ones arise. Of course, there is always the exception of hardware issues or drivers not existing for your platform, or just something not working as expected. However, for most cases, the handbook will suffice.

Here are a few tips:

• Find out what your hardware is.
• Don't deviate from the instructions. At all. Especially if you don't know what the command is doing.
• Write down every step you take and every command you enter when installing your system. That way, if you need to repeat it, you'll know where you chose what.
• Don't be frightened by the install process. Take your time if you're feeling overwhelmed. Research the commands if you aren't sure what they are doing.

Gentoo Forums

The Gentoo forums, online at http://forums.gentoo.org/ are a fine resource to find out how other people ran into similar problems (on the same distribution, even!) and what advice others had to provide.

The most important thing to do on the forums is to search for your problem first before making a post that has probably been answered dozens of times already. Try to be as specific as you can when searching, entering exact error commands or hardware model numbers and names. For example, searching for "usbcore" instead of "USB module not working" will probably help a lot.

If you do need to post a question, be as specific as possible, but eliminate any data that isn't relevant to your post so that someone else won't trip on your post looking for something different.

If you'll be posting very very long lists of code or large configuration files, use a paste service such as http://pastebin.com/ or http://rafb.net/paste/ (same for #gentoo on IRC, as well) and then provide the link in your post.

Also, remember to be courteous when you post. No one is obligated to help you, and doing so will always take time and energy out of someone's day. A good attitude welcomes response.

Finally, the Gentoo Forums have guidelines, tips and tricks of their own. If you haven't already, be sure to read the Frequently Asked Questions.

IRC

Gentoo has a lot of channels available on IRC where people can come and chat about support issues. See Gentoo Linux IRC Resources.

As a general rule of thumb, if you haven't already searched the forums or checked with Google or the handbook before stopping in IRC, you're probably going to be ignored or flamed for asking simple questions.

Asking for help in IRC channels is not too different than on the forums. Again, some simple things to remember are:

• Don't ask to ask, just ask
• State what your problem is in clear, concise terms.
• Use a pastebin service (http://pastebin.com/ or http://rafb.net/paste/ ) and refer people to the URL with a short description of what you're pasting about

IRC is a good place to ask quick questions that can be answered where someone will remember how to fix something. It's not a good place to ask for someone to walk you through how to setup your bootloader (read the webpages, forums) or how to get online during installation (see the handbook).

If someone isn't helping, don't repeat your question until someone does. If you repeat your question and nobody answers it's probably because nobody knows (or its a really simple question) and it's time to move onto the forums or search engines.

Don't get the impression (from this wiki entry or #gentoo in general) that IRC is a cold, dark place. The reality is that many people hang out there and newbies who ask the same basic general questions over and over again without doing any research of their own can really drain the brain trust that is idling in the channel, and tend to make them simply scream 'RTFM!' Don't get your feelings hurt if someone seems a little abrasive. It is a great place to sit back and watch if you'd like to pick up on spare tips and tricks. Feel free to join the conversations, just remember that well-documented questions are generally met with criticism. Don't take it personally.

Bugzilla

If you're running into some really weird issues with your Gentoo install, Bugzilla is a great place to look for some very specific details and nitty-gritty on what might be wrong.

Bugzilla is a bug tracking system that the Gentoo developers use to track what is broken (reported by the users) and what is fixed in all of the Gentoo projects (documentation, ebuilds, etc). You can view Gentoo's Bugzilla online at http://bugs.gentoo.org/

For many, this stopping place is not for the faint of heart, and so those who already know how to RTFM will most likely already be checking Bugzilla, and not reading this entry. The more common errors (such as ld linking, or gcc configuration errors) will probably show up on Bugzilla and the forums at the same time, so in most cases you can probably find the information in both places.

Here are some good places to start:

• Basic bug search
• Advanced bug search

Other Resources

This entry has only scratched the surface as to where you can look to find good documenation. There's far too many places to list just here, but here's a start.

• Gentoo Mailing Lists
• Google: Linux Search
• Gentoo-Wiki
• The Linux Documentation Project
• HOWTO Ask Smart Questions

One more great resource would be your local Linux User's Group (LUG) if one is in your area. Chances are, there are more people in your community using Gentoo Linux than you know about.

Use Your Head

A lot of hassle to finding documentation for problems and solutions can be alleviated by simply applying common sense, and doing a little research. For example, if you are looking for a program to burn CDs, did you think to search the portage tree with the keywords 'burn' or 'cd'?

Good luck on your quest for documentation! And if you learn something new, feel free to help out others in the same way, either on the forums, the wiki, IRC, or mailing lists. Spread the love. :)