The Debian designers have gone to great lengths to ensure the system is well documented. Such a pursuit has led them to include most of the necessary documentation on the Debian system you have already installed. Let's take a look at some of the resources that are available on your computer.
Almost every package which is installed under Debian installs some type of documentation information in the directory /usr/share/doc. Underneath this directory are subdirectories named after the package which installed them. Here's what my /usr/share/doc directory looks like:
jesse@storm:/usr/share/doc$ ls aalib1 diff hostname libc6-dev abiword docbook iamerican libcdparanoia0 acroread dpkg imlib-base libcomerr2 adduser dpkg-dev info libdb2 alien |
There are so many directories in /usr/share/doc that I have actually cut this short so it'll be a little more readable. Abiword is a really nice word processor which imports Microsoft Word documents and quite a few other formats as well. Let's take a look at the abiword subdirectory.
jesse@storm:/usr/share/doc/abiword$ ls README.gz changelog.Debian.gz copyright examples |
One of the really cool things about the directory /usr/share/doc is that many times the applications have examples directories in them. These subdirectories usually contain sample configuration files for programs you may be trying to use, or tips and tricks to make them work even better. You'll also notice that many of these files have the extension .gz on them. In order to view the README.gz file execute the command:
bash$ zless README.gz |
I tried this and got the following error:
jesse@storm:/usr/share/doc/abiword$ zless README.gz ------> README.gz <------ /usr/bin/zless: less: command not found |
Apparently, I didn't install the program zless when I installed my system. No problem. Now we just need to figure out which package the program zless is a part of.
![]() | Many smaller programs (like zless in this example) are packaged together with similar programs to make it easier to download them all at once. |
The tool we'll use for this is called dpkg. Just simply do this:
bash$ dpkg -S zless |
Here's what the computer told me:
jesse@storm:~$ dpkg -S zless gzip: /usr/bin/zless gzip: /usr/share/man/man1/zless.1.gz |
It appears that I forgot to install the gzip package. I can fix that easily with this:
bash$ apt-get install gzip |
and try it again. And it works:
bash$ zless README.gz ------> README.gz <------ ---------------- Release Notes ---------------- Thank you for your interest in this Preview Release of AbiWord! ---- About AbiWord AbiWord is an "Open Source" word processor. (If you would like more information about the concept of Open Source, you might start looking at www.opensource.org.) ... |
You can use the arrow keys to scroll the file up and down or use the space bar to advance one screen at a time. When you're done reading the README.gz file just simply hit the q button.
The directory /usr/doc/ is just like /usr/share/doc/. In fact, this is where all the documentation used to be stored. If you don't happen to find what you're looking for in /usr/share/doc/ then try /usr/doc/. You can use the same techniques described earlier in the /usr/share/doc/* section.
Man is just an abbreviated form of the word manual. Man pages are the core documents of any Unix system. You really need to learn how to use and read them to get the most out of your system. Also, many people get uptight if you don't at least consult them before asking questions. The easiest form to use man in is just simply this:
bash$ man name_of_program |
Where name_of_program is the name of the program you want to know how to use. Man pages are not just for programs. They also have man pages for configuration files, system commands, and a few other things. Man pages are not very popular because they are very technical in nature and can be difficult to read. Once you learn how to read them, you'll think they're the greatest thing in the world. Trust me.
Also, it's worth mentioning that at the end of a man page there are usually references to related man pages. So, if you don't find the information you're looking for make sure you check the bottom of the man page; you might otherwise miss a reference to something else related. If you want to learn more about the man program, try entering:
bash$ man man |
Don't be to intimidated. Just stick to the descriptions at first. The rest will come later.
xman is a graphical version of the program man described in the previous section. If you find man pages tedious, or just really like your mouse, try typing this at the command line:
bash$ xman & |
Alternatively, you could start xman from your menu system which should look something like Figure 1:
Whatever method you choose to start xman you should get a nice little window like that found in Figure 2:
Just click on the "Help" button to get more information or click directly on the "Manual Page" button to look up man pages.
The other day a friend of mine was having a problem with a boot disk and asked me how to fix it. So my first instinct was to try:
bash$ man bootdisk |
Unfortunately, this is what I got:
jesse@storm:~/test$ man bootdisk man: warning: /usr/share/man/man1/x-terminal-emulator.1.gz is a dangling symlink man: can't open /usr/share/man/man1/x-terminal-emulator.1: No such file or directory man: warning: /usr/share/man/man1/x-terminal-emulator.1.gz: bad symlink or ROFF `.so' request No manual entry for bootdisk |
I knew I had read about this somewhere but I couldn't seem to remember. Enter the apropos command. Apropos is kind of like saying, "I can't quite remember what that cool movie was but I know it started with 'The Good'" and having your friend jump in and give you a bunch of possible movies. That's what apropos does. So here's what I did:
jesse@storm:~/test$ apropos bootdisk mkboot (8) - makes a bootdisk |
Just like that apropos spit out an answer! Now all I had to do was:
bash$ man mkboot |
Sometimes it will give you back more than one answer. Just go through each one until you get what you're looking for.
Info pages are a great resource and usually better than man pages when they are available. Info pages are sort of like html pages only you use keyboard commands to navigate them. The best way to learn about info pages is to type:
bash$ info info |
You should get a screen which looks something like this:
File: info.info, Node: Top, Next: Getting Started, Up: (dir) Info: An Introduction ********************* Info is a program for reading documentation, which you are using now. To learn how to use Info, type the command `h'. It brings you to a programmed instruction sequence. * Menu: * Getting Started:: Getting started using an Info reader. * Advanced Info:: Advanced commands within Info. * Creating an Info File:: How to make your own Info file. |
The important thing here is the line that tells you to type "h" to begin a programmed instruction sequence. Go ahead and do that. The info program will walk you through a nice little tutorial which gives you the basics.
dpkg is the program which controls all the installation of .deb packages. This program can be used to help you find particular files or information about a program you may have installed but can't seem to get working.
Suppose you just installed a program but you can't find any documentation in the usual places (i.e. /usr/share/doc/). How would you find out where the package put the documentation? Let's pretend I didn't know where abiword installed it's documentation. I would use the dpkg command like this to find it:
bash$ dpkg --listfiles abiword |
This simply tells dpkg to list all the files that were installed with the abiword package. Here's the result of that command:
jesse@storm:~/test$ dpkg --listfiles abiword /. /usr /usr/bin /usr/bin/AbiWord_d /usr/bin/AbiWord /usr/bin/abiword /usr/share /usr/share/doc /usr/share/doc/abiword /usr/share/doc/abiword/examples /usr/share/doc/abiword/examples/en-US /usr/share/doc/abiword/examples/en-US/Latin1.abw /usr/share/doc/abiword/copyright /usr/share/doc/abiword/README.gz /usr/share/doc/abiword/changelog.Debian.gz/ |
In the example above you can see the doc directory quite nicely but in reality when I executed this command all the files scrolled right off the screen and I wasn't able to read any of them. For especially large packages with lots of files we are going to need to enlist the help of another program called grep. Here's the new command to find what we are looking for:
bash$ dpkg --listfiles abiword | grep doc |
![]() | The "|" character or pipe as it's called is typed by pressing Shift-\ |
This command tells dpkg to list all the files installed by abiword and then send that list to the program grep. grep then searches through the list looking for any occurrence of the word "doc". When grep finds the word doc on a line it prints that line to the computer screen. Here's what the output looks like:
jesse@storm:~/test$ dpkg --listfiles abiword | grep doc /usr/share/doc /usr/share/doc/abiword /usr/share/doc/abiword/examples /usr/share/doc/abiword/examples/en-US /usr/share/doc/abiword/examples/en-US/Latin1.abw /usr/share/doc/abiword/copyright /usr/share/doc/abiword/README.gz /usr/share/doc/abiword/changelog.Debian.gz |
This is much easier to read then the previous example, and as you can see, it only printed out lines with the occurrence of "doc". The files didn't scroll of the screen and it's a nice short list. I can now look in those directories and see what I can find. This might seem like a silly example, but if you look closely you can use this to search for all kinds of things. You could replace "doc" with any word you are looking for. Some examples which come to mind might be "help", "ref", "html", "config", "conf", "etc", and "examples".