Documentation

Revision / Modified: Apr. 20, 2002
Author: Tom Berger

Original documents:
http://www.mandrakeuser.org/docs/basics/bdoc.html http://www.mandrakeuser.org/docs/basics/bdoc2.html http://www.mandrakeuser.org/docs/basics/bdoc3.html

Overview

Documentation in Linux comes in packages of various sizes, from the mere listing of command line options to complete manuals.

What is...

whatis command

names the program's purpose. It queries the man page database (see below), so it only works if the program has a man page. Example:

whatis rm
rm (1)     - remove files or directories

The number after the command shows which section its man-page is in. Type <q> to leave the summary.

Command line options

Most programs supply a switch offering a short explanation on their usage. Regrettably there's no standard, so you might have to try some switches:

• Commands which require options print a help message if you issue them without options, e.g. 'rpm' or 'tar'.

• Built-in shell commands like 'alias' use the shell's help system: help command.

• System utilities usually take the '--help' parameter.

• Others will often listen to one of these: '-?', '-h' or '-help'.

If neither of these work, you have to look elsewhere.

Manuals ('Man' and 'Info' Pages)

Most commands come with either 'man' or 'info' pages:

• man command
• info command

Try 'man' first since most programs documented in the info format also have a man-page. These can be quite technical, since they are often written by the very people who wrote the program and some programmers are just not very good at writing documentation. ;-) However, they provide the most competent information about how a program works, which options it accepts and sometimes even examples on how to use them.

Docs In 'doc' Directory

Many programs come with additional documentation like README files, FAQs (Frequently Asked Questions) or even user manuals. You can find them in the '/usr/share/doc' directory (pre-7.2: '/usr/doc').

Usually these documents are part of the package you install. There's one notable exception, though, and that's the Linux kernel. You get this very useful collection of documents either if you install the kernel-sources package (then the documentation resides in '/usr/src/linux/Documentation') or by installing the separate kernel-docs package (then it's '/usr/(share)/doc/kernel-docs-[version]').

HOWTOs, FAQs, E-Books

These documents are maintained by members of the Linux Documentation Project (LDP). Some of them are available in languages other than English. The HTML version is usually included in ML (except for 7.0) and located in '/usr/share/doc/HOWTO/other-formats/html/' (pre-7.2: '/usr/doc/HOWTO/[...]'). If you prefer another format (ASCII text, PDF, PostScript), you can download the appropriate package from linuxdoc.
HOWTOs are written by experienced Linux users and currently cover more than 300 topics, like configuring special hardware, setting up and using software, transition from other operating systems, troubleshooting etc. If you don't know how to do something, have a look at them first. Most of them are written in the manner of my pages.
Even if you have the offline version installed, it's a good idea to pay a visit to the online index, since many HOWTOs are updated regularly.

The LDP also maintains other documents, like the guides, which resemble books. They cover broader topics like security, general administration, networking and the Linux kernel. Some of them are written especially with users new to Linux in mind.

A third LDP section contains the FAQ documents with the indispensable, must-read, can't-do-without Linux FAQ. Many (and I mean many) questions on Linux in general and in particular are answered here.

Books

Reading documents on a computer monitor is quite a hard job for your eyes and your mind. Either you print them, or you get yourself some 'real' books. Nowadays there are tons of books on GNU/Linux available, here is a pitiful collection of them:

• Linux in a Nutshell, by Jessica P. Hekman et al., O'Reilly, 3rd edition, 2000 is a sure bet.
  It covers all the basic bash shell commands as well as Perl, shell scripting, the editors Emacs and Vi, basic system administration and more. It's the only book on GNU/Linux I use (almost) every day.

• Running Linux by M. Welsh, M.K. Dalheimer and L. Kaufman, O'Reilly, 3rd edition, 1999, is widely regarded as the best introductory level book on GNU/Linux.
  Remarkable: it's fun to read.

• Linux: Installation, Configuration, and Use by Michael Kofler, Addison-Wesley, 2nd edition, 2000.
  Awarded 'Best of Operating Systems' in 1998, it covers almost everything: basic tasks as well as KDE, Gimp and LyX. Comes with a GNU/Linux distribution on two CDs. It's a multi-purpose book: you might as well learn GNU/Linux with it as - given its size and weight - kill everything up to the size of a grown-up cat. :-)

• Consult the Linux Reading List HOWTO by E.S. Raymond for a larger list. You may also visit the extensive Open Source Bibliography by O'Reilly.

Distribution Manuals

There are - of course - Mandrake's own manuals, available in English, German, French, Spanish and Italian: The Installation Guide and the User Guide and Reference Manual.
You find a local copy in '/usr/doc/share/mandrake/' after installation, of course it is also accessible via the desktop menu.
Red Hat also provides some excellent documentation in different formats. These are useful for older (pre-7.0) versions of ML: The Red Hat Linux Installation Guide v6.0 and the Red Hat Linux Getting Started Guide v6.0.

More Online Resources

Refer to MUO's Resources section and the Online Troubleshooting Resources HOWTO.

Finding Documentation

If you want to find out which documentation is included in an RPM run:

rpm -qld program_name if the package is already installed or
rpm -qpld package_name if not.

Example:

$ rpm -qld rpm
/usr/share/doc/rpm-4.0/GROUPS
/usr/share/doc/rpm-4.0/RPM-PGP-KEY
/usr/share/man/man8/rpm.8.bz2
/usr/share/man/man8/rpm2cpio.8.bz2

Please refer to the article on RPM if have difficulties with this (e.g. don't know which package a command belongs to).

If you want to load all these documents in a pager for reading, you can do that, too:

less $(rpm -qld rpm)

(This is called command substitution.)

Notice however, that you will have troubles reading HTML or man pages in 'less'. Better use suitable programs for them.

Handling 'man'

Some important command line options are:

• '-a' . Displays all pages that match a pattern. For example: whatis man displays this:

  man (1) - format and display the on-line manual pages
  man (7) - macros to format man pages
  man.config (5) - configuration data for man
  

  However man man only displays the first entry, man (1). Using man -a man will display the second, man (7), after having closed the first.
  This is because man pages are organized in directories according to content: 'man1' contains pages belonging to user commands, 'man2' system calls, 'man3' C functions, 'man4' file formats and device files, 'man5' configuration files, 'man6' games, 'man7' misc., 'man8' system administration, 'man9' kernel functions and 'mann' new commands. To get a man page from a specific section, use

  man section command

  e.g. man 7 man.

• '-k'. Searches the first few lines of all man pages for a keyword. Similar to the 'apropos command' command.

• '-K'. Full text search on all man pages for a given string. This may take quite a while...

man pages use the program 'less' for display. Therefore you can use all navigational shortcuts of 'less' like scrolling with <SPACE> or <RETURN>, bookmarking with <m>, searching forward with /pattern and backward with ?pattern, jumping from pattern to pattern using <n> or <N>. It is important to get used to these, since man pages can be very long. Type <h> in 'less' to get an overview on all available navigational commands.

You can use a lesser form of command line completion with the 'man' command. Type:
man tcl and hit first the <ESC> key and then <!>. The command will be completed to 'man tclsh'.
If the first letters of the man page are ambiguous or if there isn't a man page starting with these letters, nothing happens. This works with info pages, too.

man pages are stored in subdirectories of '/usr/share/man' and other places. As long as a man page is in one of these directories, 'man' will find it by looking at '/etc/man.config'. If you want to read a man page in a non-standard location, you have to supply the path to that file to the 'man' command, or use programs which are capable of rendering the 'man' macro language, like 'mc'.

Handling 'info'

info files provide multi-level manuals which can be browsed by links. These links are marked by an asterisk (*). Put the cursor on one of them and hit <ENTER> to follow this link.
Info pages are organized by 'nodes', i.e. all pages are part of one hierarchical structure. You can display the top of this structure by typing just info.
The most important navigational shortcuts are:

• <SPACE> (scrolling down page wise),
• <BACKSPACE> (scrolling up page wise),
• <b> and <e> (jump to beginning or end of node),
• <TAB> (jump to next link in text) and
• <ENTER> (follow link).

You can also navigate by nodes and levels:

• <n> (next node),
• <p> (previous node),
• <u> (one level up),
• <l> (back to previously displayed page).

<h> will give you detailed help and <?> a list of available info commands.

Searching Text Files With 'grep'

If you are looking for a string in one or more text files, use 'grep'. 'grep' searches texts for a specific pattern.
Let's say you are searching for files in '/usr/src/linux/Documentation' which contain the string 'magic':

$ grep magic /usr/src/linux/Documentation/*
sysrq.txt:* How do I enable the magic SysRQ key?
sysrq.txt:* How do I use the magic SysRQ key?

The file 'sysrq.txt', among others, contains this string in the context of discussing the SysRQ feature.

By default, 'grep' only searches the current directory. If this directory contains many subdirectories, 'grep' will list them with lines like these:

grep: sound: Is a directory

This can make 'grep's' output quite a nuisance to read. There are two ways to prevent 'grep' from doing this:

• telling it to search the subdirectories, too: grep -r
• or telling it to skip directories: grep -d skip

If you are expecting a lot of output, you should send it to program like 'less' using a pipe:

$ grep magic /usr/src/linux/Documentation/* | less

Now you can scroll the output conveniently.

An important thing to remember is that you have to provide a file filter (just add * for all files). If you forget this, 'grep' will just wait and thus block the terminal. If this happens to you, press <CTRL c> and try again.

Some of the more interesting command line options for 'grep':

• grep -i pattern files makes the search case-insensitive. The default is case-sensitive search.
• grep -l pattern files just lists the names of matching files.
• grep -L pattern files lists the names of non-matching files.
• grep -w pattern files only matches whole words, not substrings ('magic' vs. 'magical').
• grep -C number pattern files determines how many [number] lines of context are displayed around a hit.
• grep pattern1 | pattern2 files lists lines which contain either pattern1 or pattern2.
• grep pattern1 files | grep pattern2 lists lines which contain pattern1 together with pattern2.

There are also some special signs which help you to refine your search:

• \< and \> match the beginning and the ending of a word.
  Examples:
  • grep man * finds 'Batman', 'manic', 'man' etc.
  • grep '\<man' * finds 'manic' and 'man', but not 'Batman'.
  • grep 'man\>' * finds 'man' and 'Batman', but not 'manic'.
  • grep '\<man\>' only finds 'man', not 'Batman' or 'manic' or any other string.
• '^' : means 'only words with the following string which are at the beginning of a line'
• '$' : means 'only words with the proceeding string which are at the end of a line'

• If you can't be bothered with command line options, there's also a graphical interface to 'grep', called reXgrep. It offers a search engine like AND, OR, NOT syntax and some nice buttons :-). If you just need a clearer output, get fungrep.

Documentation Browsers

• pinfo: 'pinfo' runs in an terminal and displays man and info pages. It searches for an appropriate info page first and then for a corresponding man page. If it doesn't find either of them, it calls 'apropos'.
  References are provided as links, and the output is nicely colorized. You can customize colorization. 'pinfo' also adds the much needed search function to 'info'. Included on the Mandrake Linux CDs.

• KDE Help. If you happen to use KDE, you can use KDE's own help browser to search and display man and info pages. Note the syntax: man:program_name, but info:(program_name).

• Gnome Help Browser. The central help tool for the GNOME environment, which displays almost everything under the sun. The syntax for man and info pages is the same: man:program_name or info:program name.

• HTML Browsers. HTML is an increasingly popular help file format. It is much easier to write pages in than using 'man' or 'info' macros. You can bookmark the appropriate pages in your browser of choice, and use the browser's built-in search function. To search HTML pages with 'grep', use lynx' 'dump' option:

  lynx -dump file1 file2 | grep pattern

• 'TkInfo', 'TkMan', 'Xinfo', 'Xman'. X programs to display and search 'man' or 'info' pages.