Contents:

Manual pages
Info files
Other document formats
The Linux Documentation Project
Finding documents on a Debian system
Suggested reading order

# Introduction to documentation on Debian

This document is an overview of the different kinds of documentation that are available on-line on a Debian GNU/Linux system. The same kinds of documentation is available on all Linux and most UNIX systems as well.

Most of the documentation is targeted at the user of a specific program, command, or library function, but there are also some more general tutorials. The documents come as manual pages, Info files, plain text files, HTML files, and in various other formats. The Debian on-line documentation system gives access to all of them via a WWW browser by converting the documents to HTML, if possible.

## Manual pages

Manual pages are the traditional form of UNIX documentation. Each command, library function, special file, and so on, has a separate ``page'' of documentation. The manual pages follow a common format, with named sections.

NAME
  The name of the command or commands (one manual page sometimes documents several commands), and a short summary of what the command does (only a few words).
SYNOPSIS or SUMMARY
  A terse description of what options and arguments the command has. For an experienced user, the synopsis is often enough to see how to use the command.
DESCRIPTION
  The detailed description of the command.
OPTIONS
  What each of the options means. Sometimes this is not a separate section, but is included in the description.
ERRORS
  What the program does is various error situations.
FILES
  Important files that the program uses.
SEE ALSO
  Other manual pages or documents that you might also want to read.
BUGS
  Problems and restrictions in the program that you should be aware of.

Many manual pages contain many other sections, and few include all of the above.

Manual pages make it possible to find information quickly. The manual pages form the UNIX reference manual, but they are not very useful if you haven't used a UNIX system before. Most manual pages assume that you understand the common concepts of using UNIX. You should start by reading a tutorial (see below). Then, when you need to learn a new command, you can read its manual page.

Manual pages are read with the `man` command. You give the name of the manual page (usually the same as the command) as the argument. For example, to read the manual page for the `ls` command, you'd give the following command:

> `man ls`

You can also read manual pages using your WWW browser through the Debian on-line documentation system.

## Info files

The GNU Project uses the Texinfo system to produce manuals. Texinfo is a markup language, and produces either printed manuals (using the TeX typesetting system), or on-line manuals in Info format. Info files are a simple form of hypertext. They are usually structured like like books, and are usually larger than manual pages.

Few people outside the GNU Project use Texinfo, but since GNU has produced so much software, there are many Info files. Since a manual page should be short, and an Info file need not be, the Info files are sometimes easier to read.

Info files can be read directly using the GNU Emacs help system (started with `C-h i` from within Emacs), or the standalone Info browser (started with `info` from the shell). You can also read manual pages using your WWW browser through the info2www interface that comes with the Debian on-line documentation system.

## Other document formats

Most programs come with a ``README'' file, which is a simple text file, often called README that describes the program and often includes instructions on how to install it. The README is usually not important for people who use the program, but it can be interesting to read it if you want to know how things work. On a Debian system, the README's, and other similar files, are installed in a package specific directory, under `/usr/share/doc` (see below).

It is becoming more common for complicated programs to include documentation in HTML or Postscript format, in addition to (sometimes incomplete) manual pages. HTML is the markup language that WWW uses, and all such documents are easily accessible via the Debian on-line documentation system. Postscript, however, is a complicated typesetting language, and it cannot easily be converted to other formats. There is no easy way to read the Postscript manuals via the Debian on-line documentation system.

## The Linux Documentation Project

Since 1993, the Linux Documentation Project has produced FAQ's and HOWTO's and books to explain how to install and use Linux. The LDP books have been converted to HTML, but are not currently available as Debian packages, and cannot therefore be read through the Debian on-line documentation system.

## Finding documents on a Debian system

Manual pages are typically stored under `/usr/share/man`, and `/usr/local/man`. Each manual page is in its own file. They are written using an old markup language (see documentation for `groff` and the `mandoc` macros), and are formatted into a more readable format using `nroff`. Since the formatting can be slow, the formatted page is stored into `/var/catman`; that directory is automatically cleaned from old formatted versions.

Info documents are stored in `/usr/share/info`. Info files are not quite plain text, so they also need to be formatted for easier reading. However, this formatting is fast enough that the formatted version is not saved.

Each installed Debian package creates its own documentation directory below `/usr/share/doc`. For example, documentation for Debian itself is in `/usr/share/doc/debian`. All documentation that is not manual pages of Info files is stored in the package's documentation directory.

The `/usr/share/common-licenses` directory contains the common copyright statements like GPL, and `/usr/share/doc//examples` contains example configurations and programs.

## Suggested reading order

If you're new to UNIX-like systems, you should probably start with Matt Welsh's Installation and Getting Started. It includes much information about installing Linux, but that part is not relevant for a Debian system. However, the book also includes introductions on how to use Linux, and you should read those to get a feel for what using UNIX is like.

At some point, you should read the manual pages for your shell (bash), and some of the essential file handling commands (ls, less, cd, mkdir, rmdir, cp, mv, rm). You might also want to check out Midnight Commander and GNU Interactive Tools, which can be nicer to use than the traditional commands. Also read the manual for your editor (for example, Pico, ae, Emacs, Jed, vim, nvi, or elvis, depending on taste and on what is installed). After that, browse the Debian on-line documentation system and read about whatever happens to interest you.