Table of Contents
We like to fool ourselves into believing that computers are intuitive devices that are easy to use and learn. The truth is that computers are complicated tools, and it takes practice, patience and information to use these tools proficiently.
One of the most frustrating tasks new users face is finding out how to find information. A lot of documentation comes pre-installed on your computer. You can also find documentation on the Internet if you know how to search for it effectively. When written documentation is insufficient, electronic and real-life communities exist where you can find other people willing to help answer your questions. This chapter surveys these options, letting you know what documentation is available and how to access it.
The documentation on your system does not come in a single format. Some documentation forms you will run into include manual pages, GNU info files, PDF documents, HTML files, and in-application help. For the most part, you use different tools to access each of these formats. In this section we will describe the tools used to access helpfiles on your system, and the types (and quality) of documentation you can expect to find.
For the most part, we will list resources that are friendlier to new users first.
A word of caution: computer technology changes quickly, and one of the weaknesses of open source software (and of software in general) is that documentation is not always kept up to date. Some of the documentation you run across will refer to versions of software older than what is installed on your system. Some documentation will not apply to your situation at all. Having said that, even older documentation is often a good resource in learning the basics of a new program.
In-application help [UGH. YUCKY TERM.] refers to the help that you can access from the applications you run. In-application help is sometimes referred to as online help, but you usually do not need to be online (that is, connected to the Internet) to access this help.
Tooltips are your first source of information about a running program. Tooltips are small information boxes that pop up when you hover your mouse over different icons on the screen. You can often learn a lot about what a program does just by exploring the screen and reading tooltips. Similarly, you can learn about the different options available in your application of choice by exploring the drop-down menus. It is often possible to figure out the basics of a new and unfamiliar program by exploring the program menus alone.
Some applications come with manuals you can access while running the program. If your application has drop-down menus, look in the menu. A few sophisticated applications offer interactive help, where you can type in a question and search for information about the tasks you wish to accomplish.
The option of the IceWM menu opens an HTML document that lists different help resources available on your computer. Included are links to manuals for some of the major applications installed on your computer, links to the HOWTOs, and resources on the Internet that you might find helpful. Many of the documents listed in this chapter are accessible via the WCLP help document.
Many of the Debian packages on your system come with documentation in HTML format. If the dhelp package is installed (which is usually the case), you can access this documentation by using your web browser to view the contents of /usr/share/doc/HTML/index.html If for some reason the dhelp application is not installed, you can find some documentation by browsing the subdirectories in /usr/share/doc/.
Of special interest is the Debian Reference Manual. Unless you have a very small hard drive, you can access this document at ->-> of the IceWM menu.
The Debian Reference Manual contains a wealth of information about configuring and administrating Debian-based computers (which includes WCLP systems such as your computer).
This manual is aimed at non-programmers, but it assumes that you are comfortable using the command-line shell. If you are brand new to computers or brand new to Linux, you may find the entries too brief and technical to be useful. Nonetheless, it is a good place to start when learning about a topic.
The manual page (or manpage) is one of the oldest and best-supported documentation formats for Linux (and UNIX) computers. Manual pages have an unfortunate reputation for being hard to work with, but the TkMan application makes them easier to work with.
In the Debian distribution, all programs must have a manual page, but in most cases the manual page is oriented towards command-line usage. This is useful if you are programming shell scripts, customizing your startup environment or administrating your computer. Some manual pages also document keystrokes or menu options, and several contain references to related documentation and programs. However, manual pages for graphical applications such as Abiword or Dillo tend to be sparse. In these cases it is more useful to look for other documentation specific to the application you are interested in.
The command line tools to access manual pages are man and apropos. The man command displays a manual page given a name, and the apropos command searches for keywords so that you can find the name of a command to accomplish some task. For example, to find all the programs and applications that contain the word "icewm" in their title or short description, you would type
apropos icewm
in a command-line shell.
The TkMan application is a powerful graphical application for viewing and searching manual pages. You can find TkMan in -> of the IceWM menu.
Upon starting up, TkMan displays its user manual. You will likely see some warnings about "whatis" files at the top of the screen, but these are harmless. [SCREENSHOT]
Above the main display are a number of buttons and an information line, which describes the functions of each button when you click it. The TkMan manual describes the buttons and other program controls in detail, so we will briefly describe the main features.
The top left button has a picture of a page on it. When you click and hold this button it will display the sections available in the current page. You can jump to any of these sections by clicking it.
The button labelled is used to control highlighting in the manual page. If you find yourself referring to a specific passage of a manual page frequently, you might highlight the beginning of that section: select the text you want with the mouse, and press the button: the text should turn yellow. [SCREENSHOT] The highlighted section appears in the highlighting menu, which you access by clicking and holding the button.
By accessing the highlighting menu, you can quickly access frequently-accessed passages in your manual pages.
The button and the text entry box to the right are used to display and search for manual pages. If you know the name of the manual page to display, type the name in the text box and click the button. If you want to search for keywords in manual pages, enter the search term in the text box, then click and hold the button to display the Apropos entry. This will carry out an apropos keyword search and display the results in the main window. [SCREENSHOT]
The button to the right of the text entry box shows the history of pages you have visited; it reveals a menu of recently-accessed pages when you click and hold the button.
The button marked adds and removes bookmarks of pages. If you frequently access a certain page, you can visit the page and click on this button (which will become a ). This will add the manual page to the list of your bookmarks.
You can also search for text within a page. To do this, type the text to search in the textbox at the bottom of the screen, and then press the button. Use the up and down arrow buttons to visit the search results.
The button shows different categories of manual pages. Traditionally manual pages are organized into sections, where each section is reserved for different purposes. For example, section 1 documents general commands, and section 5 documents file formats.
In reading Linux documentation, you might run into commands written with a number after them: for example, somebody may reference aptitude(1) . The number in parentheses refers to the volume where the manual page can be found. Occasionally two manual pages will share a name, but be in different sections. In this case TkMan will display a button labelled , which will allow you to choose which version of the manual page to read.
By clicking and holding the button, you can visit manual pages by section. This can be useful if you would like to browse the manual pages available, or if an apropos search reveals nothing.
From the menu, you can also access the most recently accessed pages, pages with highlights, and all the pages you have visited in the past. [SCREENSHOT]
In addition to HTML and the manual page format, some program manuals are written in a format called Info, which organizes informations into a hierarchy. You can browse the info documentation installed on your computer with the program TkInfo, which can be found in the -> section of the IceWM menu.
The first screen TkInfo displays is a list of all the info manuals installed on your computer. [SCREENSHOT] Following links takes you one level deeper in the hierarchy, and clicking the button takes you one level higher. The button behaves like a "Back" button in a web browser: it takes you back to the page you visited previously.
The and buttons allow you to read info files section by section. Sometimes this form of navigation gets confusing; if you get lost in the hierarchy your best action is to use the until you get to a section you recognise.
Info files are generally used for in-depth manuals than manual pages, but most of the manuals are oriented towards command-line usage.
Documentation for the Debian packages installed on your system are stored in the directory /usr/share/doc. Inside this directory you will find a subdirectory for each installed package. For example, the icewm application comes from the packages icewm and icewm-common, so you might look at the contents of /usr/share/doc/icewm-common for documentation.
Things to look for in the /usr/share/doc/ subdirectories include:
Documents in /usr/share/doc/ are often compressed using gzip. If your file manager does not open these files correctly, you may have to use the zless command to read them. [REF zless]
A HOWTO is a tutorial written about some particular topic, such as setting command-line prompts or setting up a firewall. HOWTO documents are one of the best ways to learn about your computer and how it works. They are usually written by individual users who want to share what they have learned about some task. Although many of the topics covered by HOWTOs are aimed at intermediate or advanced users, even beginning users can learn about the kinds of things it is possible to do with Linux and open source software.
Unless you have a very small hard drive, you will find a collection of HOWTO documents in the /usr/share/doc/HOWTO/en-txt/ directory. These HOWTOs are text files compressed using gzip. Your web browser or XFE may uncompress and display these files when you double-click on them. If they don't, then you can also read these documents from the command line, using the zless command. For example, to read the Reading-List-HOWTO, open a command-line window and type the following:
cd /usr/share/doc/HOWTO/en-txt/
zless Reading-List-HOWTO.gz
For more information about using zless and the command line, see [WHERE?]
For some reason, HOWTOs are more prone to being out-of-date than other documentation. Check the publication date of the HOWTO carefully before trusting its contents. Also note that some aspects of HOWTOs (such as compiling code from source) usually do not apply to you, since you can install Debian packages.