[olug] man, info, HOWTOs, Guides, FAQs, other local docs, web sites, and search engines are your friends

[Mark A. Martin]

Sometimes people ask questions on this list that they could easily
answer for themselves by spending a few minutes reading a man or info
page or a HOWTO or by looking at the documentation for a piece of
software or hardware on their own systems or on a web site.  There
certainly have been times in the past when I have been guilty of this
(and there may be times in the future when I am guilty of it again) and
it is certainly excusable for newbies.  But reading available
documentation will not only cut down on unecessary traffic on the list
but may result in finding the answer to a question more quickly and is
an essential part of becoming adept at Linux-related problem solving. 
Consequently, I offer this brief tutorial on finding and reading
documentation.

The tutorial covers

* man pages
* info pages
* other local documentation
* HOWTOs
* LDP guides
* FAQs
* web sites
* search engines and mailing list archives

It is likely that there are others on the list that are more skilled
with documentation than I am and my knowledge is limited by the
distributions that I have experience with.  But here are some methods
and suggestions for whatever they're worth.

The "man" command
-----------------
Information on how to use a particular linux command is usually
available through the man facility.  Typing

man command

brings up the man page for "command".  For example,

man ls

displays the man page for the ls command.

The man page is displayed through the user's paging software, which is
usually "less" but is sometimes "more".  (Type "man less" or "man more"
at a command prompt if you don't know what these are.)

If you don't know what command you're looking for but you know a keyword
associated with the command, you can use

man -k keyword

to list all of the commands whose descriptions contain "keyword",
together with their descriptions.  For example,

man -k list

displays a list of commands with the keyword "list" in their
descriptions.  The ls command is on this list.  As before, the list is
displayed using the user's paging software.

Man page files have file extensions that look like .n, .n.gz, or .n.bz2,
where n is an integer that referes to the manual "section" that the page
resides in.  Different sections correspond to different categories.  The
pages are written in nroff, which is an older text processing language. 
Man pages are typically stored under /usr/man, /usr/local/man, and
potentially other similarly named directories.  Each directory such as
/usr/man contains directories with names like man1, man2, ... that
contain the pages in the different sections of the manual.

You can display a page in section n that pertains to a particular
command by executing

man n command

Sometimes it is necessary to specify the section number to access a man
page, sometimes because there are pages in different section that have
the same name.  Also, the section numbers are usually included in the
"SEE ALSO" sections of man pages, which refer to pages that might also
be relevant.

There is an X application for browsing man pages called xman.  It is
probably on your system. You can also browse man pages through the Gnome
help browser.

Info pages
----------
Rather than using the man facility like traditional UNIX programmers,
GNU programmers, i.e. Free Software Foundation programmers, have decided
to standardize on their own version of hypertext documentation called
info pages.  Info pages may be read using the "info" command.  Typing
"info" at a command prompt brings up the main page of the info system. 
The first time you use info, type "h" to start the info tutorial.  This
will give you an overview of the info system and how to navigate within
it.  Many of the navigational command are the same as in emacs.

To find the info page for a particular command, you must wade through
the tree of categories until you arrive at the page for the given
command.  There is no search facility.  So it may take a little flailing
around before you find the information you're interested in.  Many
people, including me, find info pages less accessible and less helpful
than traditional man pages due to having to remember yet another
navigational system and having to traverse a tree to find help for a
particular command.

Browsers that render info pages, such as the Gnome help browser, have
made the navigation of info pages much easier over the past couple of
years.  Such browsers make my complaint about the difficulties of
navigation meaningless.  However, a user must still discover where to
look for a page within the info tree and where to look is not always
apparent.

Local Documentation
-------------------
Many major distributions define a particular directory as a repository
of local documentation.  On Red Hat-based systems (and possibly others),
this directory is /usr/doc.  On Red Hat-based systems, the documentation
for a particular package is located in /usr/doc/pkg_name.

For example, "rpm -q lilo" shows that the LILO package installed on my
system is lilo-0.22-17mdk (17th Mandrake build of LILO 0.22) and the
corresponding documentation resides in /usr/doc/lilo-0.22.  A recursive
listing of /usr/doc/lilo-0.22 shows

/usr/doc/lilo-0.22:
CHANGES  COPYING  INCOMPAT  QuickInst*  README  doc/

/usr/doc/lilo-0.22/doc:
Makefile            bootloader.tex  map.tex        rlatex*   user.tex
README              fullpage.sty    other.fig      t2a.pl
Technical_Guide.ps  image.fig       other.tex      tech.dvi
User_Guide.ps       image.tex       parameter.fig  tech.tex
bootloader.fig      map.fig         parameter.tex  user.dvi

In particular, /usr/doc/lilo-0.22/doc/User_Guide.ps is very useful.

Local documentation may also reside in other places such as under
/usr/share, /usr/local/doc, /usr/local/share.  Unfortunately, the Linux
Filesystem Hierarchy Standard (http://www.pathname.com/fhs/) does not
define a specific place.  If you are using rpm, one way to look for
documentation associated with a particular package is to use rpm to list
the files in the package and look for files that seem to contain
documentation.

For example, executing "rpm -ql xpdf" yields

/etc/X11/applnk/Applications/xpdf.desktop
/usr/bin/pdfimages
/usr/bin/pdfinfo
/usr/bin/pdftopbm
/usr/bin/pdftops
/usr/bin/pdftotext
/usr/bin/xpdf
/usr/doc/xpdf-0.90
/usr/doc/xpdf-0.90/CHANGES
/usr/doc/xpdf-0.90/README
/usr/man/man1/pdfimages.1.bz2
/usr/man/man1/pdfinfo.1.bz2
/usr/man/man1/pdftopbm.1.bz2
/usr/man/man1/pdftops.1.bz2
/usr/man/man1/pdftotext.1.bz2
/usr/man/man1/xpdf.1.bz2

There is documentation in /usr/doc/xpdf-0.90 on this list and there are
also man pages in /usr/man/man1, including a few that you may not have
expected such as a man page for pdftops.  Also look for postscript, pdf,
text, or HTML files and files with names like README, CHANGES, or FAQ.

Reading local documentation may require using various applications. 
You'll need to use gv or ghostview to read postscript files, gv, xpdf,
or acrobat reader to read pdf files, a web browser such as netscape to
read HTML files, and an info browser or the info command to read info
files.

HOWTOs
------
HOWTOs usually contain information on larger topics that you may need
help with.  They provide information on topics such as how to properly
secure your Linux box (Security-HOWTO), how to perform parallel
processing on a Linux cluster (Parallel-Processing-HOWTO), how to
replace your hard drive (Hard Disk Upgrade Mini-HOWTO), or how to use
your Linux box to reduce energy use and cut down on wasted paper
(Ecology_HOWTO).  There are HOWTOs that cover more extensive topics,
usually classified as just "HOWTOs", and HOWTOs that cover smaller, more
specific topics, usually classified as "Mini-HOWTOs"

HOWTOs are part of the Linux Documentation Project
(http://www.linuxdoc.org).  However, the HOWTO format is popular and
there are HOWTOs that are not (yet) part of the LDP.  You may read or
download HOWTOs from the LDP web site (and many other places such as
http://www.linuxresources.com) or you may already have local copies of
the HOWTOs under /usr/doc/HOWTO (or another distribution-specific
directory).  HOWTOs are often useful for giving you a broad overview of
a topic as well as answering specific questions.

HOWTOs are available from the LDP in many formats including text,
postscript, PDF, docbook, and HTML.

LDP Guides
----------
LDP guides are entire books about Linux that are freely available as
part of the Linux Documentation Project (http://www.linuxdoc.org).  In
particular, I recommend the guide "Installation and Getting Started" for
a good general introduction to Linux.  These books are available in a
variety of formats that depend on the specific guide.  Some of these
guides are also available as books from O'Reilly and Associates
(http://www.oreilly.com).

You may also already have several of these guides on your system.  Look
in the directory /usr/doc/LDP or look for packages with names such as
sag (Systems Administrators' Guide), nag (Network Administrators'
Guide), and so forth.  See the LDP web site for the names of other
guides.

FAQs
----
FAQs are lists of Frequently Asked Questions together with answers. 
These are often very useful.  There are FAQs for Linux available through
the Linux Documentation Project (http://www.linuxdoc.org) and there are
often FAQs associated with particular pieces of software that may be
included with the software or available on the web site associated with
the software.  FAQs are usually available as HTML files or occasionally
text files

Web Sites
---------
Another important source of information about a piece of software or
hardware is the web site associated with that software or hardware.  A
web site may contain extensive documentation in any of the forms
described above.  The URLs for web sites are sometimes listed in
associated man or info pages or may be found using a search engine as
described below.  The web site of the vendor or manufacturer may be
helpful when looking for information on a piece of hardware, a driver,
or firmware (such as BIOS) associated with the hardware.

Search Engines and Mailing List Archives
----------------------------------------
Another way to find information on a topic that you're having trouble
with is to use a search engine.  I usually use this method as a last
resort because it may be difficult to locate information germane to your
specific question.  On the other hand, you may end up trying this first
if you just need to find the web site associated with a particular piece
of software.

The first step in using a search engine is to choose the engine you're
going to use.  When doing this, it is important to keep in mind how the
different search services work.  For example, Yahoo
(http://www.yahoo.com) employs people to group web sites into a
hierarchy of categories.  It is also necessary to submit your site to
Yahoo for evaluation to have it included on Yahoo (although Yahoo uses a
secondary automated search service in case a regular Yahoo search
doesn't yield anything).  Therefore, I use Yahoo when I want to find a
list of pages covering a certain category or when I'm relatively certain
that the site I'm looking for will have been registered.

Other search engines do not rely on people submitting information and do
not use people to categorize information.  They use programs that search
the web and create large databases of sites.  Different search engines
contain listings for different portions of the web and the searches they
perform have different characteristics.  My favorites are Google
(http://www.google.com) and Metacrawler (http://www.metacrawler.com). 
Google is very fast and seems to employ a good search algorithm. 
Metacrawler submits your queries to a large number of other search
engines and thereby searches the web from a number of different
perspectives.  I tend to use Google or Metacrawler when I am searching
for a specific piece of information that I expect to be on a single
page.  You might also want to look at Doc Searl's article on page 10 of
the September 2000 "Linux Journal" for a comparison of search engines.

The second step for effective searching on the web is to carefully
create a search string that will uniquely identify what you're looking
for as much as possible.  It often helps to group words into phrases
(since otherwise search engines just look for pages that contain all of
the words) and to pair phrases with words that narrow the search.  Most
search engines allow you to search for phrases by enclosing the words in
double quotes.  You can usually use the boolean operators AND, OR, and
NOT in your searches too, although the syntax may vary between search
engines.  There is usually a page on the search engine site that
describes the correct syntax for the search engine.

For example, suppose you wanted help with X Windows on Solaris.  (This
is a little contrived but will hopefully will make my point.)  Searching
for

windows

would bring up pages, probably 50 bazillion of them, that describe
physical windows as well as MS Windows.  Using the phrase

"X windows"

would narrow the search to slightly fewer millions of pages and using
the search string

"X windows" solaris

might bring the total down to a few thousand.  Including the particular
version you were having trouble with in your search string might even
bring the number of pages down to a managable number.

Searching for information on specific Linux topics will often yield
pages within mailing list archives.  This is useful because it may be
helpful to follow the thread containing the message (forward and
backward), even if the particular message you found doesn't contain the
information you need.  It is often also possible to go to the main page
for the mailing list archive containing the message and search the
archive using a search engine that is local to the archive.  Even if
there is no search facility on the mailing list site, there are usually
pages containing lists of subject lines from messages submitted during
particular periods of time and you can use the "find" facility on your
web browser to search for keywords in the subject lines.  Then you can
read through promising threads to look for worthwhile information.

There are also large repositories of mailing list archives that are
maintained at various sites arond the world.  I'm out of steam with
regard to writing this tutorial right now so I'll have to leave it to
you to find some of these.  They are often searchable and sometimes very
helpful.  The mailing list archives of the major distributions also tend
to be searchable and very helpful.

The OLUG mailing list archive itself is searchable.  So don't forget to
look there as well.

I hope that this message helps make people aware of the vast quantity of
documentation that is available and helps them access it.  Happy problem
solving!

Mark
-- 
---------------------------------------------------------------------------
Mark A. Martin					Dept of Applied Mathematics
http://www.amath.washington.edu/~mmartin	University of Washington
---------------------------------------------------------------------------

---------------------------------------------------------------------
To unsubscribe, e-mail: olug-unsubscribe at bstc.net
For additional commands, e-mail: olug-help at bstc.net