Getting Help: Documentation and Other Sources

With more than 1,000 programs included in the distribution, even a book this size cannot cover everything in your copy of SUSE Linux.

There are plenty of places to go to learn more about Linux and help you troubleshoot problems with applications. Many of these are included in the references at the end of this and the other chapters of this book.

Printed Documentation and the SUSE Help Center

SUSE is one of the few software companies anywhere that still provides printed manuals that try to help users beyond installing the product. Buying the boxed version of SUSE Linux gives you two thick books, the Administration Guide and User Guide. Although you can sometimes tell that they have been translated from German, these books have a fairly easy-to-read style that will get you using the product in short order.

Both manuals were also converted into HTML pages and integrated into the electronic SUSE Help Center. This is a boon for the user in two ways: You don't have to rummage around the office to find the books, and you can run a full-text search of both books for the information you're looking for.

The online versions of the manuals are updated regularly, even after your version of the distribution is current, so check for updates at least a couple times a year to be sure you have the latest version.

Searching the Help Center

Open the Help Center by typing susehelp from the shell, or click the life preserver icon in KDE or GNOME. Putter around the Table of Contents to see what is included, or click the Search tab to find something specific. Help-Center search uses the ht://dig engine used on many websites (see Figure 1.2).

Figure 1.2. The SUSE Linux Help Center offers the full text of the SUSE Administration Guide and User Guide. It's searchable, too.

The first time you want to run a search, click Create Search Index first so the engine has something to look at. You'll see a set of online books to index; check them all so you can access everything. If you happen to be on a slower machine, results may come faster if you just index the two guides. Click the HTML Search tab to learn a little more about ht://dig and where it is installed on your system (along with learning that the SUSE developers use a Perl script to create the index). When you're ready, click OK to create the index. When you're finished, check the Status column in the main window. Each indexed book should say OK, and what you did not index will say Missing.

The search screen is much like an advanced web search screen where you can select what to search, how many results to return, and how to treat multiple word searches. By default, if you ask Help Center to find the terms "spam" and "filter," the engine will search for documents with both words in it (a Boolean AND). If you want to find either term, choose OR in the Method box. The default search scope is the two manuals. To search all the components, choose All. If you think your answer may be in an info or man page (more on these later), check these boxes, too; the Scope Selection box will switch to Custom automatically. Click Search to find your answer. Results will appear in the right window. Click a hyperlink to see the pertinent article.

Man and Info Pages

One of the earliest forms of online help is the humble Unix man page.

In the early days of Unix, the manual came as a series of three-ring binders sent out from Bell Labs with each copy of the operating system.

The manual would expand with each new tool or command included. At some point, someone got the bright idea to create electronic files of the manual pages so everyone running the OS could get help without having to roam the lab to find the page they needed. This is how the man(ual) page was born, along with the man command.

Man pages are compressed text files, located in /usr/share/doc. They are usually tersely written (usually by the application's programmers), with information listed under particular categories specified by convention. These include a command reference, a summary of what each option/switch does, the author of the page and/or the program. Occasionally, there are even known bug statements.

To learn more about using the man program to read man pages, type man man at the command line. When you press Enter, a paging program called groff will load and display the page. Press the spacebar to scroll from screen to screen. When you're done reading, press the q key to return to the shell prompt.

More complex programs can tax the man page format, so the info help format was created. These pages, created with a version of the TeX document formatting system, include a hierarchical structure, hypertext links for easy navigation between documents, and keyboard and mouse navigational tools. The first time you use info (often when looking for help in the Emacs text editor), it can be a little overwhelming, but it is not too hard to deal with after you have a feel for it. Read the info tutorial (type info info) to learn more.

Many man pages are on the web, and you can search both man and info pages in the SUSE Help Center. Start looking for man pages at the Linux Documentation Project (see the following tip). Then try going to http://www.google.com/linux and search.

Tip

Use apropos and what is to find what you need. If you know what you want to do but are not sure about the tool to use, type apropos <keyword> at the shell prompt. Apropos will search the NAME section of each man page (which includes a brief description of the tool's purpose) and display a list of programs and commands that may help. It's not foolproof, but even if you don't find exactly the right tool, you may get on the road to finding what you really need.

The whatis program does the inverse of apropos. Suppose you couldn't remember what the acronym "bash" stood for. Type whatis bash and you'll know!

SUSE Online Support

The SUSE support website at http://www.suse.com/us/private/support/index.html is a great resource for getting help. There is a mix of paid and free online support.

When you're trying to find a solution for a problem, click Support Database from the main Support menu, or just go directly to the Support Database at http://portal.suse.com/sdb/en/index.html. This database is searchable, either via keyword or full text. Besides German and English, the database exists in French, Spanish, Czech, and Hungarian (Magyar).

Note

At the time of writing, Novell was still in the process of converting the suse.com web pages to novell.com servers. If you can't find a page listed here, check the http://www.novell.com/linux home page to see where it may have moved to.

The Online Support menu on the main support page links to some interesting HOWTO documents, showing you step-by-step how to accomplish many tasks, from partitioning your hard drive to comparing HTML editors to encrypting email.

Novell also offers what they call "Cool Communities," on their website. This is an area where assorted experts offer tips on a regular basis. There's even a Wiki page, where you can post your own articles and questions, at http://wiki.novell.com/index.php/SUSE_LINUX_Professional.

Tip

Learn more about wikis in Chapter 16.

The Linux Documentation Project

The place to start for more user-friendly guides to Linux tools and applications is the Linux Documentation Project. Frequently Asked Questions (FAQ) lists, HOWTO pages, and more detailed guides to applications are written, reviewed, and edited by a team of volunteers and compiled at the LDP site, www.tldp.org.

Because all the documents here are formatted in DocBook XML, everything here is presented in a variety of formats; at least one should meet your needs. Site search is powered by Google and is right on the home page, so finding items related to your question is quick and easy. You can also easily see the most recently updated documents or just browse through categories to educate yourself.

The howtoenh packages included on the SUSE Linux disk are not updated often, but can be helpful. They are not installed by default, so if you want them, use YaST.

The SUSE Mailing Lists

SUSE sponsors 51 electronic mailing lists in multiple languages to allow users to help each other with problems and questions. The general list in English, suse-linux-e, generates some 150 messages per day on all topics, but most lists are more specialized. Read descriptions of all the lists, with links to the list archives, at http://www.suse.com/us/private/support/online_help/mailinglists/. You can also subscribe to multiple lists on this page; just check the box next to the list you want to subscribe to and type your email address at the bottom of the page. You must subscribe to a list to post a question.

The chief problem with the archives is that they are not directly searchable. You can browse the monthly archives, which are sorted by thread for solutions, but this can be time consuming. Fortunately, Google and most other search engines can do site-specific searches.

To search all the lists for Perl-related issues, the Google syntax is

 perl site:lists.suse.com. 

To search just suse-linux-e, change the site to lists.suse.com/archive/suse-linux-e/.

Your favorite search engine may use different syntax; check the engine's support page for specific information.

Because these lists are high traffic, make sure to check the archives before posting a question yourself. Chances are whatever you are experiencing, someone else is, too. To get the best help from the list, keep these things in mind:

• When you ask a question, describe any problem as specifically as possible. Include pertinent sections of log files, with the error messages you received.

• Describe your efforts to solve the problem. "I've searched the Help Center and the archives. I saw the discussion about a similar problem and tried the solution, but it didn't work (or here's why my problem is different from that one)."

• Be patient! Although sometimes questions can be answered and problems solved in minutes, that's not the norm. If people don't respond, wait a few days (if you can) before asking again. The person who has your answer just may be busy at that moment. If you can't wait for a solution, try another list, or contact your local Linux User Group (see the next section).

• After you have asked a question, hang around for a while. Perhaps you can answer someone else's question what goes around comes around.

There is also a SUSE Users Yahoo Group. Sign up or view the archives at http://groups.yahoo.com/group/suselinuxusers/.

Linux User Groups

When you really want a live, knowledgeable human being to help you with a problem or teach you something, most users have just two choices: hire a consultant for big bucks or find your closest friend who knows something about computers. Problem is, that tech-savvy friend is probably pretty well versed in working with one or another of the proprietary operating systems produced on the West Coast, but might not know a lot about Unix or Linux. What do you do now?

Fortunately, if you live reasonably close to a decent-sized population center or town with a college campus, there is likely to be a gaggle of Linux-savvy people just a few mouse clicks away your local Linux User Group (LUG). These people usually meet once a month for speakers, demonstrations, occasional door prizes, and general camaraderie. Most active LUGs have websites, and many have email lists where problems get solved, equipment gets traded, and opinions about various technical and Linux-related issues are shared. If you are slightly intimidated by the thought of installing Linux on your computer, LUGs frequently hold "install fests" where experienced folks will install SUSE or another distribution (your choice) on your system and give you pointers along the way. As with most everything Linux, this all comes free of charge.

Now you can't just pick up a phone book and call the LUG office to get started, but it is not especially hard to find one either. You can check your daily newspaper for meeting notices (these are often found on the business pages) or call your public library for information. Some communities still have specialty computer magazines left over from the tech boom days that list user groups of all kinds.

The fastest way to find a LUG is probably online. Linux Gazette magazine hosts the Groups of Linux Users Everywhere (GLUE) site at http://glue.linuxgazette.com. They are organized geographically, so you can browse through the listings or search from the main page. Every group has an email contact, and many have a URL listed. If a website is not listed here, do not assume the group doesn't have one. Searching is an option. Both Google and Yahoo have Linux User Group directories, but rather than sort through a complicated directory structure, just type "<yourtown> Linux User Group" into the regular search box.