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

[Nathan Brown]

Thanks,  This is a whole lot of information that is very valuable and I will
use this more often than you can imagine.
My problem with this is that I read, I do and it does not work.  At that point
I don't know what to do.  This gets very frustrating for me, but I will use
this information a lot.

very appreciative
Nate

"Mark A. Martin" wrote:

> 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


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