A P P E N D I X  C

Getting Further Help

So you've read through this book and have a good working knowledge of Linux. Ubuntu is running exactly as you want it to, and things are going okay. But then you hit a brick wall. Perhaps you want to perform a task but simply don't know how. Or maybe you know roughly what you need to do but don't know the specifics. Although this book tries to be as comprehensive as possible, it can't cover every eventuality.

You need to find some help, but where do you turn? Fortunately, many sources of information are available to those who are willing to help themselves. Linux contains its own series of help files in the form of man and info pages, and these are good places to start. In addition, some programs come with their own documentation. If neither of these sources provides the help you need, you can head online and take advantage of the massive Linux community around the world.

Read the Manual!

Before asking for help online, it's important that you first attempt to solve your problems by using Linux's built-in documentation. If you go online and ask a question so simple that it can be answered with a little elementary research, you might find people replying with the pithy admonition RTFM. (This stands for Read The <expletive> Manual or, in more refined company, Read The Fine Manual). In other words, do some basic research and then come back if you're still stuck.

It's not that people online don't want to help. It's that they don't like it when people are too lazy to help themselves and expect others to do even the slightest work for them. Although not all Linux people you encounter will take such a hard line, doing a little homework first can provide answers to a lot of questions, removing the need to ask others. This is particularly true when it comes to the fundamentals.

Documentation typically comes in three formats: man pages, info pages, and README files.

Man Pages

man pages are the oldest form of UNIX documentation. In the old days, after an individual had created a piece of software, he or she would write a brief but concise man page in order to give others a clue as to how to operate it. The programmer would come up with a few screens of documentation that could be called up from the command prompt. This documentation would outline what the software did and list all the ways in which it could be used.

Nowadays, depending on the software package, man pages are sometimes created by technical writers, but the concept of providing essential information still applies. man pages under Linux provide all the information you need about how to use a particular command or piece of software.

Sounds great, doesn't it? Alas, there's a problem: man pages are written by software engineers for software engineers. They expect you to already understand the technology being discussed. This is illustrated very well by the man page for wodim, software that can be used to burn CD images to disc. You can view this man page by typing man wodim at the command prompt.

The first line of the man page states, “Wodim is used to record data or audio compact discs on an Orange Book CD-recorder or to write DVD media on a DVD-recorder.”

Most of that is clear, but what do they mean by Orange Book? They don't explain. (If you're curious, head over to http://searchstorage.techtarget.com/sDefinition/0,,sid5_gci503648,00.html.)

Farther down in the man page, you see, “Wodim is completely based on SCSI commands … Even ATAPI drives are just SCSI drives that inherently use the ATA packet interface as [a] SCSI command transport layer.”

What's SCSI, or ATAPI for that matter? Again, the man page doesn't explain. (By the way, they're methods of interfacing with storage devices attached to your computer.)

But why should man pages explain as they go along? Their function is to describe how to use a piece of software, not to provide a beginner's introduction to technology. If they did that, a single man page could run to hundreds of pages.

In other words, man pages are usually not for complete beginners. This isn't always the case and, because Linux sees widespread usage nowadays, man pages are sometimes created with less knowledgeable users in mind. But even so, the format is inherently limited: man pages provide concise guides to using software. Luckily, there are some tips you can bear in mind to get the most from a man page. But before you can use those tips, you need to know how to read a man page.

How to Read a Man Page

To read a man page, you simply precede the command name with man. For example, to read the man page of wodim, a piece of software used to write ISO images to CD-R/RW discs, type the following command:

This opens a simple text viewer with the man page displayed. You can use the cursor keys to move up and down line by line, or you can use the Page Up and Page Down keys (these are sometimes labeled Pg Up and Pg Dn) to move page by page. You can search by pressing the forward slash key (/). This highlights all instances of the word you type. You can search for other examples of the word in the document by pressing the N key (pressing Shift+N will search backward). The average man page will include many headings, but the following are the most common:

Name: This is the name of the command. There will also be a one-sentence summary of the command.

Synopsis: This lists the command along with its various command options (sometimes known as arguments or flags). Effectively, it shows how the command can be used. It looks complicated, but the rules are simple. First is the command itself. This is in bold, which indicates it is mandatory. This rule applies to anything else in bold: it must be included when the command is used. Anything contained within square brackets ([]) is optional, and this is usually where you will find the command options listed. A pipe symbol (|) separates any command options that are exclusive, which means that only one of them can be used. For example, if you see [apple|orange|pear], only one of apple, orange, or pear can be specified. Usually at the end of the Synopsis listing will be the main argument, typically the file(s) that the command is to work on and/or generate.

Description: This is a concise overview of the command's purpose.

Options: This explains what the various command options do, as first listed in the Synopsis section. Bearing in mind that command options tell the software how to work, this is often the most useful part of the man page.

Files: This lists any additional files that the command might require or use, such as configuration files.

Notes: If this section is present (and often it isn't), it sometimes attempts to further illuminate aspects of the command or the technology the command is designed to control. Unfortunately, Notes sections can be just as arcane as the rest of the man page.

See Also: This refers to the man pages of other commands that are linked to the command in question. If a number appears in brackets, that means the reference is to a specific section within the man page. To access this section, type man <section no.> command.

Although there are guidelines for the headings that should appear in man pages, as well as their formatting, the fact is that you may encounter other headings, or you may find nearly all of them omitted. Some man pages are the result of hours, if not days, of effort; others are written in ten minutes. Their quality can vary tremendously.

Tips for Working with Man Pages

The trick to quickly understanding a man page is decoding the Synopsis section. If you find it helps, split the nonobligatory command options from the mandatory parts. For example, wodim's man page says that you must specify the dev= option (it's in bold), so at the very least, the command is going to require this:

Then you should skip to the Options section and work out which options are relevant to your requirements. While you're there, you'll also need to figure out what the dev= command option requires.

Although the command options contained in square brackets in the Synopsis section are, in theory, nonobligatory, the command might not work satisfactorily without some of them. For example, with wodim, we use the -speed command option, which sets the burn speed, and also the -v option, which provides verbose output (otherwise, the command runs silently and won't display any information onscreen, including error messages!).

Another handy tip in decoding man pages is understanding what standard input and standard output are. In very simple terms, standard input (stdin) is the method by which a command gets input—the keyboard on most Linux setups. Standard output (stdout) is where the output of a command is sent, which is the screen on most Linux setups. Often a man page states that the output of a command will be sent to standard output—in other words, unless you specify otherwise, its output will appear onscreen. Therefore, it's necessary to specify a file to which the data will be sent, either by redirecting the output, or by using a command option to specify a file. For example, the genisoimage command can be used to create ISO images from a collection of files for subsequent burning to CD. But unless the -o option is used to specify a filename, genisoimage's output will simply be sent to standard output—it will appear on the screen.

Finally, here's the best tip of all for using man pages: don't forget that man has its own man page. Simply type man man.

Info Pages

man pages date from the days of relatively primitive computers. Back then, most computers could only display page after page of text and allow the user to scroll through it. In addition, memory and disk space were scarce, which is why some man pages are incredibly concise— fewer words take up less memory.

The Texinfo system is a valiant attempt by the GNU Project to overcome the shortfalls of man pages. Often this is referred to as info, because that's the command used to summon Texinfo pages (normally, you type info command).

For starters, info pages are more verbose than the equivalent man pages, and that gives the author more space to explain the command or software. This doesn't necessarily mean that info pages are easier to understand, but there's a better chance of that being the case.

Second, info pages contain hyperlinks, just like web pages. If you move the cursor over a hyperlinked word, usually indicated by an asterisk (*), you can proceed to a related page. In a similar sense, pages are linked together so that you can move back and forth from topic to topic.

The bad news is that the man page system is far more popular and established than Texinfo. A programmer who creates a new application, unless the program is part of the GNU Project, will not likely bother with an info page but will almost certainly produce a man page.

In fact, in many cases, typing info command will simply bring up the man page, except in the software used to browse info pages.

However, nearly all the GNU tools are documented by using info pages, either in their own pages or as part of the coreutils pages. For example, to read about the cp command and how to use it, you can type this:

To browse through all sections of the coreutils pages, type this:

Because man pages are so established, everyone expects to find one for every utility. So most utilities that have info pages will also have man pages. But in such a case, the man page will state near the end that the main documentation for the utility is contained in an info page, and you may find it more fruitful to use that instead.

Navigating through info pages is achieved via the keyboard and is something of an art. But, as you might expect, there's a user-friendly guide to using info: just type info info. Remember that words preceded with an asterisk are hyperlinks, and you can jump from link to link using the Tab key.

README Files and Other Documentation

Some programs come with their own documentation. This is designed to give users the information they need to get started with the program (as opposed to the man page, which is a concise and complete guide to the software). Alternatively, program documentation sometimes gives a brief outline of the program's features.

The files are usually simple text, so they can be read in any text editor or word processor, and are typically called README. Under Ubuntu, these documents are usually stored in a program-specific directory within /usr/share/doc (although a small minority of programs use /usr/doc).

Not all programs are friendly enough to provide such documentation, but even so, you'll still find a directory for the software in /usr/share/doc. This is because the software might also come with a getting started guide written by the Ubuntu package maintainer. Such guides detail specifics of using the software under Ubuntu, such as where configuration files are located or how the program interoperates with other software on the system. Sometimes this documentation is written by a Debian package maintainer, because nearly all Ubuntu software has its origins in the Debian project (www.debian.org).

In addition, the directory will probably contain copyright information, explaining the software license used by the software, as well as a CHANGELOG, which is a text file listing features that have been added to each release of the software. The directory might contain some other files too, detailing where to send information about bugs, for example.

Viewing the README documentation is easy. For example, for the sudo command, you could type this:

Sometimes the README documentation is in a compressed tarball, in which case it will have either a .tar.gz or a .tar.bz2 file extension. However, less is clever enough to realize this and extract the document for reading.

Getting Help Online

If you can't figure out the answer by referring to the documentation, you have little choice other than to look online. Fortunately, Linux benefits from a massive community of users, all of whom are usually willing to help each other.

The best way of getting help is to visit a forum. There you can post messages for others to reply to. Alternatively, you might choose to sign up for a mailing list. This is a way of sending e-mail to several hundreds, if not thousands, of people at once. Any individual can then reply. Mailing lists often have the benefit of allowing personal attention and interaction, but this comes at the expense of each subscriber receiving a whole lot of mail.

Forums

The official Ubuntu project forums are located at www.ubuntuforums.org. You'll find forums for just about every need, from security to beginner's issues, but the most popular by far is the one devoted to the current release of Ubuntu. Look in the General Help forum if your question isn't specifically related to one of the other technology areas listed.

Before you can post, you need to register by providing an e-mail address. This is required to keep down the quantity of unwanted junk postings to the forum.

You might think it fine to post a new question immediately after registering, but don't forget the simple RTFM rules mentioned at the beginning of this appendix: if you don't do elementary research first and try to solve your own problem, you may elicit a hostile response from the other posters, especially if your question is one that comes up time and time again and has been answered several times.

So, first use the comprehensive search facility provided with the forums. For example, if you're looking for advice on getting a Foomatic D1000 scanner working, use that as a search term and see what comes up. The chances are that you won't be the first person who has run into problems with that piece of hardware, and someone else may have already posted a solution.

Often you need to read the full thread to find an answer. Someone may start by asking the same question as you and, with the help and guidance of the forum members, finds a solution, which is given several messages later.

In addition, some individuals write their own HOWTO guides when they figure out how to do something. These are normally contained in the Tutorials & Tips forum, under the Other Community Discussions heading.

If you're unable to find a solution by searching, consider posting your own question. Keep your question simple, clear, and concise, because no one likes reading through acres of text. If possible, provide as many details about your system as you can. You will almost certainly want to provide the version number of the Linux kernel you're using, for example. You can find this version number by typing the following in a GNOME Terminal window:

In addition, any other details you can provide may prove handy. You definitely should mention the version of Ubuntu you're using, which is Lucid Lynx (often referred to simply as Lucid). If you're asking about hardware, give its entire model name and/or number. Don't just ask for help with a Foomatic scanner. Ask for help with a Foomatic D1000 scanner, model number ADK1033, Revision 2. If you're asking about a piece of software, provide its version number (to find that, click Help About).

Sometimes in their replies, other forum members may ask you to post further details or to provide log files. If you don't understand the question, simply ask the poster to give you more details and, if necessary, instructions on what to do. Just be polite. Explain that you're a newbie. If you think the question is extremely obvious, say so—apologize for asking what may be a stupid question, but explain that you've tried hard to answer it yourself but have failed.

Don't forget that the Ubuntu forums include the Absolute Beginner Talk forum, where fundamental questions are asked all the time.

Mailing Lists

Using the forum's search function also has the advantage of searching the archives of the mailing lists.

Mailing lists have a number of advantages and disadvantages. The advantages are that a mailing list provides an excellent way to learn about Ubuntu. All you have to do is read through the e-mail messages you receive in order to partake of a constant information drip-feed. In addition, some mailing lists are designed to make public announcements, so you'll find it easy to learn about the latest happenings in the Ubuntu community.

Mailing lists also have a terrific sense of community. They offer a neat way of getting to know other Ubuntu users and talking to them. E-mails often drift off-topic into humor and general discussion.

The disadvantages of mailing lists are that you can easily receive in excess of 200 messages a day, depending on which mailing list you join (although you can also opt to receive period digests of recent messages; these arrive in the form of a single daily, weekly, or monthly e-mail). Even if you have a moderately fast Internet connection, that quantity of messages can take a long time to download. In addition, you'll need to sort out any personal or business e-mail from the enormous quantity of mailing list traffic (although the mailing list messages usually have the list title in square brackets in the subject field; you can therefore create a mail rule that sorts the mail according to this).

You can learn more about the Ubuntu mailing lists at https://lists.ubuntu.com.

Other Official Sites

The Official Ubuntu Documentation is an ongoing community effort to create simple and effective instructions on the use of Ubuntu. In truth, there is nothing presently on the site that isn't already described in this book, so its usefulness for you is limited, but it might be ideal to send the link to a friend or relative who's new to Ubuntu. In addition, you might want to take a look at the Ubuntu wiki: https://wiki.ubuntu.com. Once again, this is largely community generated. It contains a whole world of fascinating information about Ubuntu, but can be somewhat difficult to navigate and tends to be aimed at higher-level Ubuntu users, such as developers. However, it's an excellent place to learn “off-the-wall” Ubuntu knowledge, such as how to get Ubuntu working with particular hardware.

Third-Party Sites

Of course, the Ubuntu project doesn't have a monopoly on sites that discuss Ubuntu. Several third-party web sites are worth at least an occasional visit, and other forum web sites are devoted to Linux.

One we visit on a regular basis is the Ubuntu Geek blog: www.ubuntugeek.com. Written by a team of dedicated Ubuntu experts, this blog is packed full of tips for all levels of Ubuntu users. In addition, we like to visit http://linuxhelp.blogspot.com, which is a similar blog written by a Linux user who uses Ubuntu and likes to share tips and techniques.

Perhaps the king of third-party Ubuntu sites is Ubuntu Guide: http://ubuntuguide.org. This contains brief instructions on how to do a variety of common tasks under Ubuntu, such as installing certain types of software or administering particular hardware. It covers a lot of the same ground as this book, but is still worth investigating if you want to browse through some excellent tips and advice.

One site to check on a regular basis for news about future releases of Ubuntu and upcoming applications is OMG! Ubuntu!, which you can find at http://www.omgubuntu.co.uk. There you can the most up-to-date information about the development of new software, new trends in the development of Ubuntu, and analyses of the future of Ubuntu.

Finally, one of the best Linux forums and general advice sites can be found at www.linuxquestions.org. This has a forum dedicated specifically to Ubuntu, but also contains hundreds more devoted to just about every aspect of Linux, including forums for beginners.