12.1 Included Help Resources

There are several places where you can find online documentation shipped with your product:

Desktop Help Centers

The help centers of both the KDE desktop (KDE help center) and the GNOME desktop (Yelp) provide central access to the most important documentation resources on your system in searchable form. These resources include online help for installed applications, man pages, info pages, and the Novell/SUSE manuals delivered with your product. Learn more about your desktop's help center in Section 12.1.1, Using the KDE Help Center and Section 12.1.2, Using GNOME Yelp.

Documentation in /usr/share/doc

This traditional help directory holds various documentation files and the release notes for your system. Find more detailed information in Section 12.1.3, Documentation Directory.

Man Pages and Info Pages for Shell Commands

When working with the shell, you do not need to know the options of the commands by heart. Traditionally, the shell provides integrated help by means of man pages and info pages. Read more in Section 12.1.4, Man Pages and Section 12.1.5, Info Pages.

Separate Help Packages for Some Applications

When installing new software with YaST, the software documentation is installed automatically in most cases and usually appears in the help center of your desktop. However, some applications, such as The GIMP, may have different online help packages that can be installed separately with YaST and do not integrate into the help centers.

12.1.1 Using the KDE Help Center

From the KDE desktop, you can access the KDE help center in various ways: If you need information from within an application, simply click the application's Help button or press F1 to open the application's documentation in the help center. If you start the help center from the main menu, or from the command line with khelpcenter, you are taken to the main window of the help center from which you can browse the help topics.

Figure 12-1 Main Window of the KDE Help Center

The menu and the toolbar provide options for printing contents from the help center, searching the currently displayed page, and navigating and customizing the help center. The display field in the right part of the window always shows the currently selected contents, such as online manuals, search results, or Web pages.

The navigation area in the left part of the window contains several tabs:

Contents

Presents a tree view of all available information sources. The help center addresses various target groups, such as users, administrators, and developers. Click the book icons to open and browse the individual categories. Under the heading Administration, for example, you can also browse man (manual) and info (information) pages associated with command line programs. The help center also provides access to some online databases that cover special hardware and software issues for your product. All these sources can be searched conveniently once a search index has been generated.

The contents of your help center depends on which software packages are currently installed and which languages are selected as your system languages.

Glossary

Provides a quick reference where you can look up the definitions of words that might be unfamiliar to you.

Search Options

Holds options for the full text search of the help center. You can combine several search criteria.

Searching the Help Center

To use the full text search KDE help center offers, generate a search index and set the search parameters. If the search index has not yet been generated, the system automatically prompts you to do so when you click the Search tab.

  1. To search for a term, click Search Options and enter the search string.

  2. To combine your search strings with operands, click Method and select the operand to use.

  3. Choose an option from Max. Results to limit the number of hits to display.

  4. To restrict your search to certain types of documentation, choose an option from Scope. With Default, a predefined selection of documents is searched. All includes all types of documents in the search. Custom lets you define which documents to include in your search. Just activate the documents you want in the list.

  5. When you have set the options according to your wishes, click Search. The search results are then displayed as a list of links in the display field and can be navigated with mouse clicks.

Generating a New Search Index

  1. To create a new search index, select Settings > Build Search Index from the menu. A window opens, showing a list of documentation currently available in the help center.

  2. Select the documents to integrate in the search index and click Build Index. After the index has been generated, you can use the full text search.

12.1.2 Using GNOME Yelp

On the GNOME desktop, to start Yelp directly from an application, either click the Help button or press F1. Both options take you directly to the application's documentation in the help center. However, you can also start Yelp from the main menu, or from the command line with yelp and then browse through the main window of the help center.

Figure 12-2 Main Window of Yelp

The menu and the toolbar provide options for navigating and customizing the help center, for searching and for printing contents from Yelp. To view a table of contents, click Help Topics. The help topics are grouped into categories presented as links. Click one of the links to open a list of topics for that category. To search for an item, just enter the search string into the search field at the top of the window.

12.1.3 Documentation Directory

The traditional directory to find documentation in your installed Linux system is /usr/share/doc. Usually, the directory contains information about the packages installed on your system, release notes, manuals, and more.

NOTE: Contents Depends on Installed Packages

In the Linux world, many manuals and other kinds of documentation are available in form of packages, just like software. How much and which information you find in /usr/share/docs also depends on the (documentation) packages installed. If you cannot find the subdirectories mentioned here, check if the respective packages are installed on your system and add them with YaST, if needed.

Novell/SUSE Manuals

We provide HTML and PDF versions of our books in different languages. In the manual subdirectory, find HTML versions of most of the Novell/SUSE manuals available for your product:

Start-Up

Guides you through the installation and basic configuration of your system. For newcomers, the manual also introduces basic Linux concepts such as the file system, the user concept and access permissions and gives an overview of the features openSUSE offers to support mobile computing. Provides help and advice in troubleshooting.

KDE Quick Start

Gives a short introduction to the KDE desktop and some key applications running on it.

GNOME Quick Start

Gives a short introduction to the GNOME desktop and some key applications running on it.

Reference

Gives you a general understanding of openSUSE and covers advanced system administration tasks. It is intended mainly for system administrators and home users with basic system administration knowledge. It provides detailed information about advanced deployment scenarios, administration of your system, the interaction of key system components and the set-up of various network and file services openSUSE offers.

Novell AppArmor Quick Start

Helps you understand the main concepts behind Novell® AppArmor.

Novell AppArmor Administration Guide

Contains in-depth information about the use of Novell AppArmor in your environment.

Lessons For Lizards

A community book project for the openSUSE distribution. A snapshot of the manual written by the open source community is released on an equal footing with the Novell/SUSE manuals. The lessons are written in a cook book style and cover more specific or exotic topics than the traditional manuals. For more information, see http://developer.novell.com/wiki/index.php/Lessons_for_Lizards.

If more than one language is installed, /usr/share/doc/manual may contain different language versions of the manuals. The HTML versions of the Novell/SUSE manuals are also available in the help center of both desktops. For information where to find the PDF and HTML versions of the books on your installation media, refer to the openSUSE Release Notes. They are available from your installed system under /usr/share/doc/release-notes/ or online at http://www.novell.com/documentation/opensuse110.

HOWTOs

If the howto package is installed on your system /usr/share/doc also holds the howto subdirectory in which to find additional documentation on many tasks relating to the setup and operation of Linux software.

Package Documentation

Under packages, find the documentation included in the software packages installed on your system. For every package, a subdirectory /usr/share/doc/packages/packagename is created that often holds README files for the package and sometimes examples, configuration files, or additional scripts. The following list introduces typical files to be found under /usr/share/doc/packages. None of these entries is mandatory and many packages might just include a few of them.

AUTHORS

List of the main developers.

BUGS

Known bugs or malfunctions. Might also contain a link to a Bugzilla Web page where you can search all bugs.

CHANGES , ChangeLog

Summary of changes from version to version. Usually interesting for developers, because it is very detailed.

COPYING , LICENSE

Licensing information.

FAQ

Question and answers collected from mailing lists or newsgroups.

INSTALL

How to install this package on your system. As the package is already installed by the time you get to read this file, you can safely ignore the contents of this file.

README, README.*

General information on the software, for what purpose and how to use it.

TODO

Things that are not implemented yet, but probably will be in the future.

MANIFEST

List of files with a brief summary.

NEWS

Description of what is new in this version.

12.1.4 Man Pages

Man pages are an essential part of any Linux system. They explain the usage of a command and all available options and parameters. Man pages can be accessed with man followed by the name of the command, for example, man ls.

Man pages are displayed directly in the shell. To navigate them, move up and down with PgUp and PgDn. Move between the beginning and the end of a document with Home and End. End this viewing mode by pressing Q. Learn more about the man command itself with man man. Man pages are sorted in categories as shown in Table 12-1 (taken from the man page for man itself).

Table 12-1 Man Pages—Categories and Descriptions

Number

Description

1

Executable programs or shell commands

2

System calls (functions provided by the kernel)

3

Library calls (functions within program libraries)

4

Special files (usually found in /dev)

5

File formats and conventions (/etc/fstab)

6

Games

7

Miscellaneous (including macro packages and conventions), for example, man(7), groff(7)

8

System administration commands (usually only for root)

9

Kernel routines (nonstandard)

Each man page consists of several parts labeled NAME, SYNOPSIS, DESCRIPTION, SEE ALSO, LICENSING, and AUTHOR. There may be additional sections available depending on the type of command.

12.1.5 Info Pages

Info pages are another important source of information on your system. Usually they are more verbose than man pages. To view the info page for a certain command, enter info followed by the name of the command, for example, info ls. You can browse an info page with a viewer directly in the shell and display the different sections, called nodes. Use Space to move forward and Backspace to move backwards. Within a node, you can also browse with PgUp and PgDn but only Space and Backspace will take you also to the previous or subsequent node. Like for the man pages, press Q to end the viewing mode. Not every man page comes with an info page and vice versa.

With KDE or GNOME desktop, you can also access (or print) man pages and info pages:

KDE

In Konqueror, to view the man page for ls, type man:/ls in the location bar. If there are different categories for a command, Konqueror displays them as links. To display the info page for grep, for example, type info:/grep.

In the KDE help center, check out Administration in the table of contents to browse man pages and info pages.

GNOME

Run yelp man:ls or yelp info:ls to display the man or info page.

Figure 12-3 Viewing a Man Page With Konqueror