Debian help system
From NewbieDOC
- Jesse Goerz
- jwgoerz@users.sourceforge.net (author)
- Jonathan Eisenstein
- jeisen@users.sourceforge.net (publisher)
- Chris Lale
- chrislale AT users DOT berlios DOT de (publisher)
Go to NewbieDOC index
Revision History
Revision 0.2 | 4th May 2001 | Revised by Jesse Goerz | ||||||||||||||||||||||||||||||||||||
Added /usr/doc/*, xman, more info on using mailing lists, correction on zless reference, and minor corrections to info gathering progs. http://newbiedoc.sourceforge.net/general/help-system.html.en | ||||||||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||||||||
Revision 0.3 | 29th September 2001 | Revised by Jesse Goerz | ||||||||||||||||||||||||||||||||||||
Added info pages. | ||||||||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||||||||
Revision 1.0 | 5th April 2002 | Revised by Jonathan Eisenstein | ||||||||||||||||||||||||||||||||||||
Checked and revised by project editor. Lots of stuff moved around. A lot of text added. | ||||||||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||||||||
Revision 2.0 | 7th April 2002 | Revised by Jonathan Eisenstein | ||||||||||||||||||||||||||||||||||||
Pegged for release. After a major rewrite, and to match the CVS, it's now v2.0. | ||||||||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||||||||
Revision 2.1 | 7th April 2002 | Revised by Jonathan Eisenstein | ||||||||||||||||||||||||||||||||||||
A few minor corrections in layout after seeing the built HTML. | ||||||||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||||||||
Revision 2.2 | 7th February 2006 | Revised by Chris Lale | ||||||||||||||||||||||||||||||||||||
Modified for NewbieDOC wiki by converting source to wikitext. Updated some links and images. Modified section on plog. | ||||||||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||||||||
Revision 2.3 | 26th November 2007 | Revised by Chris Lale | ||||||||||||||||||||||||||||||||||||
Reformatted for newbiedoc package. | ||||||||||||||||||||||||||||||||||||||
This document is intended to help Debian newbies learn about ways in which they can find information to solve problems they have while using Debian GNU/Linux. Many thanks to Brian Potkin for his direct and accurate information about
1 IntroductionMany people who use Linux say that Debian is the hardest distribution to use. This is probably true for someone who is trying out Linux for the first time. Don't worry if this describes you. After reading this document, you will learn the basic information gathering skills you will need to find solutions to most of the problems that you will encounter. This document describes the Debian help system. Debian doesn't really have a formal help system, in that, all the information resides in one place or program. One of the great things about Debian is the multitude of resources which are readily available without cost. It will take some getting used to at first, but once you have mastered how to gather information about your problem, the solutions will come easily. Note that many of these resources are not specific to the Debian system. Unless otherwise noted, each feature can be found on most Linux systems. 2 What's Installed?The Debian designers have gone to great lengths to ensure the system is well documented. This pursuit has led them to include most of the necessary documentation on the Debian system for the packages you have installed. Let's take a look at some of the resources that are available on your computer. 2.1 /usr/share/doc/*Almost every package that is installed under Debian installs some type of documentation information in the directory aalib1 diff hostname libc6-dev abiword docbook iamerican libcdparanoia0 acroread dpkg imlib-base libcomerr2 adduser dpkg-dev info libdb2 alien Since there are so many directories in README.gz changelog.Debian.gz copyright examples One of the really cool things about the directory An easier and more logical way to read compressed files is to use the 'zless' command. This command automatically uncompresses the file using $ zless README.gz Tip: If you get an error about a command not found, you may be missing the less package. zless is installed by default on Debian systems with the gzip package, but less , which zless depends on, may not be. If you need help installing missing packages, see the Newbiedoc "apt-get intro".------> 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 http://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 2.2 /usr/doc/*The directory 3 The Online Manual3.1 The ManualOnce, in the early days of UNIX, users had the standard manuals available in print, on their shelves. 9 books were available, each one gigantic and hard to use. Someone eventually had the idea to make it standard to have all of these books on the UNIX system in the form of the man command, where it could be edited easily when new information became available, not to mention the added ease of having the manuals searchable and read quickly. These manuals are usually your first target when you have a problem, as nearly every aspect of your system is covered there. Not only are most commands covered in the online manual, but often configuration files as well as functions for programming in Linux can be found. However, many users feel intimidated by man pages because they are often technical in nature and can be difficult to read for newbies. Once you get the hang of reading them, you'll find that the man pages are the greatest source of help on any system. 3.2 Man Page LayoutManual pages have a very specific format that every official page should follow. Here is a sample, the documentation for the uname command. To read it, I type: $ man uname uname(1) uname(1) NAME uname - print system information SYNOPSIS uname [OPTION]... DESCRIPTION Print certain system information. With no OPTION, same as -s. -a, --all print all information -m, --machine print the machine (hardware) type [...] -v print the operating system version --help display this help and exit --version output version information and exit AUTHOR Written by David MacKenzie. REPORTING BUGS Report bugs to <bug-sh-utils@gnu.org>. COPYRIGHT Copyright C 2000 Free Software Foundation, Inc. [...] SEE ALSO The full documentation for uname is maintained as a Texinfo manual. If the info and uname programs are properly installed at your site, the command info uname should give you access to the complete manual. NAME: Here you get a brief description of the command after its official name SYNOPSIS: The usage of the command, with optional segments listed in brackets. When [OPTION] is specified, it means that the command can have the options listed under the next section added to it. DESCRIPTION: Detailed information about the command, including options that can be added to it. Unless specified either here or in the synopsis, you can add as many of these options as you want. SEE ALSO: This is an important section of the man page that is often overlooked. If the information you are looking for isn't available in this page, it may be available in one of the pages listed here. Also listed here is information referencing the info command, if that information exists. A description of the info command is in the next section. Using 3.3 xman
$ xman & Alternatively, you could start Figure 1. Starting xman from your GUI menu Whatever method you choose to start Figure 2. The xman program Just click on the "Help" button to get more information or click directly on the "Manual Page" button to look up man pages. 4 Info Pages4.1 What are Info Pages?While man pages are great sources of information about a command or concept, the fact that it provides one long page means that longer documents are hard to read. The info format was developed as a way to store more comprehensive instructions on your system. If a particular command is more complicated than a man page can document, the author commonly writes both a man page and an info page. While the man page will be a simple reference to the command and its options, the info page will be a longer reference, like a manual. To make it easier to read longer documents, info pages are split up into sections, with links between them, much like a web site. You should feel comfortable very quickly when using 4.2 Using Info PagesYou can start the $ 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 text you see at the bottom of the screen followed by :: are the links to other pages in this document. You can use your keyboard to put the cursor anywhere on the words of the link, and enter to select it. You may have some trouble navigating the pages, so here's a quick list of important keys: Table 1. Important keys and their functions
You can also use a mouse to navigate the info pages. Just click on a link to follow it. 4.3 xinfoIf you'd rather use a graphical interface to browse your info files, you can use the program 5 Other Help CommandsWhile man pages and info pages are the most reliable sources of information on a Linux system, there are other ways to obtain information if you still can't find your answer. For instance, what if you don't know the command you're looking for? 5.1 aproposThe 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: $ man bootdisk Unfortunately, this is what I got: No manual entry for bootdisk I knew that I had read something about boot disks before, but I couldn't seem to remember where. This is where the $ apropos bootdisk mkboot (8) - makes a bootdisk Just like that, $ 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. 5.2 Using dpkg to find information
Suppose you just installed a program but you can't find any documentation in the usual places (i.e. $ dpkg --listfiles abiword This simply tells /. /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 $ dpkg --listfiles abiword | grep doc This command tells /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". For more information about using 6 Online resourcesThere are a lot of online resources for Debian. I won't be able to cover them all here, but I will cover the ones I use when I have problems or I'm just trying to learn something new. 6.1 Debian home pageThe Debian home page (http://www.debian.org) is the central source for online information. There is so much to cover here that I'm going to break it out into a couple of sections. I highly recommend you go to the Debian web site and check it out. You will find more information on what Debian is about, Debian related news, security alerts and much more. 6.2 Debian mailing listsThe Debian mailing lists are the one thing which make it such an incredible distribution to use. No other distribution can claim to have such "round the clock" excellent support services for free. Debian has over 20 mailing lists covering subjects from running an ISP with Debian to issues of security. If you can think of it, Debian probably has a mailing list for it! The best way to get familiar with the Debian mailing lists is to visit the mailing list web site (http://www.debian.org/MailingLists/). You will get some basic information about the sites and how they operate. When you're ready to subscribe to a mailing list go to the subscription page. The most important mailing list to subscribe to for new users of Debian is the debian-user mailing list. Be warned though, the debian-user mailing list is a high-volume list. It's not uncommon to get 75 or more emails a day. Subscribing to mailing lists does bring with it some responsibilities. Here's a quick list of some of the things you ought to do when posting to the list:
site:lists.debian.org
Here are some things you should NOT do when posting to the mailing lists:
6.3 Debian GNU/Linux FAQThe Debian GNU/Linux FAQ is a very extensive document which covers a lot of (go figure) Frequently Asked Questions. You can check it out here: http://www.debian.org/doc/FAQ/. 6.4 Finding packagesNeed to find out what a specific package does? Looking for a specific package? Trying to install a specific program but you don't know the name of the package it's in? Try here: http://packages.debian.org/, or search using Google, prefixing your search terms with: site:packages.debian.org 6.5 Debian documentation projectThe Debian Documentation Project (http://www.debian.org/doc/ddp) is an ongoing project to provide quality documentation on the Debian GNU/Linux operating system for free. This is a great place to start looking when you have questions that haven't been answered elsewhere. You may also wish to browse this area in your free time, as there is a great wealth of knowledge in these guides and manuals. This is a great place to start looking when you have questions that haven't been answered elsewhere. You may also wish to browse this area in your free time, as there is a great wealth of knowledge in these guides and manuals. 6.6 NewbieDOC ProjectOf course, there's always the NewbieDOC Project (http://newbiedoc.berlios.de), which aims to provide answers for commonly encountered problems that new users of Debian may encounter. 7 Information gathering programsI'm covering these programs here just so you have a quick reference and know that they are available. Most of these programs are much more powerful and can do many more things than I'll explain. You may not ever have to use these but they may come in handy when trying to gather information so you can post an accurate question to a mailing list. 7.1 Using a terminalUsing a terminal can sometimes help you get information about a problem program. If you're running X this is really nice. Let's say that my word processing program is acting weird and won't work the way I'd like to. All I need to do is open up a terminal and execute the command to start Figure 3. Using a terminal to gather information about a malfunctioning program As you can see in the terminal window I used the following command to open abiword: $ abiword & You can make this work with any X program. Just make sure you use the "&" (Ampersand) after the actual programs command name. Then you can just cut and paste the information in the terminal window into a file or email and use it to ask questions. 7.2 plog
$ plog Then in another terminal try and start your ppp connection. Here's what mine looks like when I shutdown my ppp connection. storm:/home/jesse# plog -f Apr 8 23:15:14 nexus pppd[22001]: sent [LCP EchoReq id=0x28 magic=0xca942c68] Apr 8 23:15:15 nexus pppd[22001]: rcvd [LCP EchoRep id=0x28 magic=0x55aae757] Apr 8 23:15:44 nexus pppd[22001]: sent [LCP EchoReq id=0x29 magic=0xca942c68] Apr 8 23:15:44 nexus pppd[22001]: rcvd [LCP EchoRep id=0x29 magic=0x55aae757] Apr 8 23:16:11 nexus pppd[22001]: Terminating on signal 15. Apr 8 23:16:11 nexus pppd[22001]: Script /etc/ppp/ip-down started (pid 22411) Apr 8 23:16:11 nexus pppd[22001]: sent [LCP TermReq id=0x2 "User request"] Apr 8 23:16:12 nexus pppd[22001]: rcvd [LCP TermAck id=0x2] Apr 8 23:16:12 nexus pppd[22001]: Connection terminated. Apr 8 23:16:12 nexus pppd[22001]: Connect time 21.0 minutes. Apr 8 23:16:12 nexus pppd[22001]: Sent 23101 bytes, received 177378 bytes. Apr 8 23:16:12 nexus pppd[22001]: Hangup (SIGHUP) Apr 8 23:16:12 nexus pppd[22001]: Waiting for 1 child processes... Apr 8 23:16:12 nexus pppd[22001]: script /etc/ppp/ip-down, pid 22411 Apr 8 23:16:12 nexus pppd[22001]: Script /etc/ppp/ip-down finished (pid 22411), status = 0x100 Apr 8 23:16:12 nexus pppd[22001]: Exit. If you're having problems with your ppp connection this can really help in finding the answer. 7.3 /var/log/syslog
# tail -f /var/log/syslog 7.4 tcpdump
7.5 dumpNeed. 7.6 lspci
jesse@storm:~/test$ /sbin/lspci -n 00:00.0 Class 0600: 8086:122d (rev 02) 00:07.0 Class 0601: 8086:122e (rev 02) 00:07.1 Class 0101: 8086:1230 (rev 02) 00:0e.0 Class 0300: 5333:8811 =========divider======================== jesse@storm:~/test$ /sbin/lspci -v 00:00.0 Host bridge: Intel Corporation 430FX - 82437FX TSC [Triton I] (rev 02) Flags: bus master, medium devsel, latency 64 00:07.0 ISA bridge: Intel Corporation 82371FB PIIX ISA [Triton I] (rev 02) Flags: bus master, medium devsel, latency 0 00:07.1 IDE interface: Intel Corporation 82371FB PIIX IDE [Triton I] (rev 02) (prog-if 80 [Master]) Flags: bus master, medium devsel, latency 64 I/O ports at ffa0 00:0e.0 VGA compatible controller: S3 Inc. 86c764/765 [Trio32/64/64V+] (prog-if 00 [VGA]) Flags: medium devsel, IRQ 11 Memory at ff000000 (32-bit, non-prefetchable) 8 Appendix A: LicenceCopyright © 2001, Jesse Goerz, NewbieDoc project. jwgoerz@users.sourceforge.net Copyright © 2002, Jonathan Eisenstein. jeisen@users.sourceforge.net Copyright © 2006-2007, Chris Lale. chrislale AT users DOT berlios DOT de
Go to NewbieDOC index |