Linux University staff meetings, when they happen, (In reality these tend to be prolonged coffee breaks at the local cafe) are often times of vigorous discussions on various topics. So the other day, we asked Simon, one of our staff authors a loaded question:
“What is one of the first things a new Linux user should learn?”
Simon looked at us, thought for a moment and simply said: “How to RTFM” – meaning “how to read the fine manuals.”
We asked Simon to write an article about this, and after a few days of nagging, an email from Simon arrived. Here is what it said:
How to RTFM
Reading man pages
Man pages, short for manual page, are the traditional form of documentation for command line tools on Linux (and Unix). The current crop of man pages has a history dating back to the 80’s, when Unix didn’t care in the least about user friendliness, and so they tend to be highly technical and have a form and language all their own.
Fortunately, they can be read reasonably easily with some practise, and are a very valuable source of information for the vast collection of command line tools that helps make Unix and Linux uniquely powerful.
Structure of a Linux man page
Man pages follow a standard structure, though like with Linux and Unix there are a number of different standards that they follow. The simplest structure, and the one that all the others are derived from, starts with a synopsis, followed by a detailed description section, and finally some end-matter boilerplate.
The synopsis is a brief and rather cryptic summary of how the program can be used. It lists all the options and arguments that the program recognises and gives a brief indication of how they can be combined. Options are the ‘-b’ or ‘–blah’ part of the synopsis – they let you modify the behaviour of the program, and come in short (-b) and long (–blah) forms. Options can take arguments, either in the form ‘-b foo’ or ‘–blah=foo’. Mutually exclusive alternatives are described with the ‘|’ character – i.e. ‘foo|bar’. Finally, when an option or argument is optional this is indicated by surrounding it in square brackets.
Fortunately, you can mostly ignore the synopsis – it’s most useful as a reference once you’re already familiar with using a program. Before you reach that point the most useful section of a man page is the description.
The description section contains a detailed description of what the application does, along with a list of all the options, arguments, and what they do. This is the real guts of the man page – when you’re trying to figure out how to make the program do what you want, you’ll spend most of your time looking through the description, reading the information about each option and figuring out whether it helps you toward your goal.
This section may be broken out into a number of parts, with some extra bits on top of the basic description. The most useful of these extras is an examples section, with a set of examples of how the program is actually used. These examples can be a lifesaver – if they’re included in the man page the best way to use them is to as the basis for your command line. Copy the example and then replace the example file names and so on with your details.
Quite often there will be information about bugs or odd behaviour, error messages, environment variables, and other snippets like this. Most of it isn’t very relevant to everyday use, since it documents special cases or things that are only relevant for advanced users. However, it’s always nice to know that the information is there for those odd times when you might need it.
At the end of the man page is a bunch of meta-data about the document itself – the authors, copyright information, and frequently some contact information about the document authors and the program authors. A big thing here is an email address or other contact information for reporting bugs – in general the developers of a program love to be told about bugs, and will be very helpful in fixing them once they’re told. It’s a good way to help them out – you may not be able to write code for them, but if they don’t hear about bugs they’ll never be able to fix them.
The final part of the man page is one of the most useful: the ‘see also’ section. This is a list of related applications and man pages: generally you can simply use the man program to read this documentation, the same as the man page you’re reading in the first place. There may also be links to other documentation, on-line or in books or similar, which can also be useful.
How to read a man page
Now you know what to expect from a man page, how should you read it? Man pages aren’t like a story where you start from the beginning and read straight through to the end – it pays to pick the bits you need out of them while skipping the parts that aren’t relevant. The trick is to know how to find the relevant bits.
Assuming you know roughly what you want to do the place to start is with the description, in particular the description of what the program actually does. This should tell you whether the program will do what you want, or whether you should go looking for something else that will. Read the general description in full to find this out.
Once you’ve decided to give this program a try you should quickly flick through the list of options looking for keywords. For example, if you want to know how to list all files in a directory look for the keyword ‘all’, and quickly read about any options that look relevant. This can be helped using the search function, which can be brought up by hitting the ‘/’ key and typing in the search term. You can jump to the next instance of the term using ‘n’, and the previous instance using ‘N’.
Check to see if there are any examples listed, and if there are, base your command line on the example that seems most relevant. If there aren’t any, start with the plain command name and build from there.
If there is an option allowing you to do a dry run – i.e. to run your command without any actual changes being made – you should make use of it. Unix commands are very unforgiving, and if you make even a trivial typo it can have disastrous consequences (some time you should try running ‘rm -rf * ~’, but only on a machine where you don’t mind losing your home directory ;-).
Finally, if you find that you need more information or that the program doesn’t do what you wanted, you should look at the ‘see also’ section to try and find something that will.
Apropos
So how do you decide what man page to read in the first place? This is where being able to search the man database is useful, and that’s what apropos does. To search for a keyword in every man page on the system, simply type ‘apropos word’, and let it run. It will print out the name of all the man pages that contain the word you search for along with a short description, which you can then browse through to find likely looking candidates. Just be aware that there are often enormous numbers of man pages on a Linux system, so you can easily get hundreds of lines of output! The same functionality can be accessed by running ‘man -k’.
The only other thing to remember about apropos is that it only searches the man pages of installed programs – to find documentation for programs that aren’t installed you’ll probably need to hit Google and have a look on-line. Fortunately, various groups have put the full set of man pages up on their web servers, so using Google you can often find exactly the same thing you’d find if it was installed on your computer.
Simon
To find out more about Simon, please visit our Authors page