% Nick Urbanik <nicku@nicku.org>
% Copyright 2000 under the conditions of the GNU Free Documentation License,
% a copy of which is available at http://www.gnu.org/copyleft/fdl.html
% Copy and modify freely as long as this paragraph remains intact.
% Suggestions for improvement (and the improvements themselves!) welcome.
\chapter{Finding Documentation}
\label{cha:FindingDocumentation}
{\mns

\subsection{Objectives}

After completing this section, you will be able to:
{\myss
\begin{itemize}
\item Identify sources of information to answer your particular
  questions
  
\item Be familiar with the main sources of documentation on your
  machine:
  \begin{itemize}
  \item man pages
  \item info
  \item documentation in the {\fn /usr/share/doc} directory.
  \item Ultimate documentation: the source code
  \end{itemize}
    
\item Make some of that documentation accessable through a web
  browser

\item Identify all the documentation that is part of any software
  package

\item Be able to locate documentation from the Linux Documentation
  Project, including \emph{HOWTOs} and \emph{Guides}
    
\item Know how to find information from other people through the
  Internet, news groups and mailing lists
\end{itemize}
}

\section{Documentation everywhere?}
\label{sec:where?}

\begin{itemize}
\item Linux has a \emph{huge} amount of documentation
\item Much of it is installed on your hard disk
\item For large distributions, there may be an additional few
  many megabytes of documentation available (e.g., the
  documentation \CDROM with Red Hat Linux)
\item The only problem is: ``how do I find the documentation that I need
  to answer my questions?''
\end{itemize}


\section{Where is the documentation on my computer?}
\label{sec:oncomputer}

\begin{itemize}
\item manual pages (read using {\cmdn man} command)
\item info (read using {\cmdn info} command or {\cmdn emacs})
\item documentation in the {\fn /usr/share/doc} directory.
\item documentation in the {\fn /usr/src/Linux/Documentation} directory.
\item The ultimate documentation: the source code
\end{itemize}

\section{Some main sources of information from the Internet}
\label{sec:internet-documentation}
\begin{itemize}
\item The Linux Documentation Project: \url{http://tldp.org/}
  provides these documents in many formats:
  \begin{itemize}
  \item \acro{HOWTO}s about a large number of topics
  \item Guides: free online books
  \end{itemize}
    
\item Search using Google: \url{http://www.google.com/}
    
\item Groups in \url{http://www.google.com/}, and usenet
    
\item Red Hat (and other distributions) provide plenty of online
  information.  These URLs are current 30~Oct 2003:
  \url{http://www.redhat.com/docs/},
  \url{http://www.redhat.com/docs/manuals/linux/}.  After you have
  read the \emph{Getting Started Guide}, I particularly recommend the
  \emph{Red Hat Reference Guide}, and the \emph{Red Hat Customisation
    Guide}\@.
\end{itemize}    


\section{Mailing Lists}
\label{sec:mailing-lists}

\begin{itemize}
\item A \emph{mailing list} is a discussion group over email
  \begin{itemize}
  \item Mostly have a narrow technical focus
  \item a great way to get help from an expert on the subject.
  \end{itemize}
\item You \emph{subscribe} to a mailing list by:
  \begin{itemize}
  \item Send email to the list server, or fill in a simple web form
  \item The list server sends you an email
  \item You reply to that email
  \end{itemize}
\item Any subscribed user can send an email to the list
  \begin{itemize}
  \item All subscribed users will receive that email
  \item Set one mail folder for each list
  \item Set your email software to filter all list email into the
    right folder, to keep list email separate from your personal
    email.
  \end{itemize}

\item Examples:
  \begin{itemize}
  \item Red Hat and Fedora lists:
    \url{http://www.redhat.com/mailman/listinfo}
  \item the Apache lists:
    \url{http://httpd.apache.org/lists.html}
  \item the Samba lists:
    \url{http://us1.samba.org/samba/archives.html}, plus many others
    (I subscribe to about 40!)
  \end{itemize}
\end{itemize}


\section{Asking Questions on a Mailing List}
\label{sec:asking-questions-the-smart-way}

\begin{itemize}
\item Before sending questions to a mailing list, read Eric Raymond's
  \emph{How To Ask Questions The Smart Way}:
  \url{http://www.catb.org/~esr/faqs/smart-questions.html}
\end{itemize}

\section{Online Magazines}
\label{sec:online-magazines}
\begin{itemize}
\item Some online magazines include:
  \begin{itemize}
  \item Alan Cox's Portaloo:
    \url{http://www.linux.org.uk/cgi-bin/portaloo} This site is
    surprisingly useful; it collects the headlines from about 25 web
    sites with technical news, so that you can review the headlines
    from all the sites, and click on any headline that looks
    interesting.  This takes you directly to the story.  It saves me a
    lot of time.
  \item Apache Week: \url{http://www.apacheweek.com/}
  \item LWN.net (used to be Linux Weekly News):
    \url{http://lwn.net/}
  % \item Perl Month: \url{http://www.perlmonth.com/}
  \item NewsForge: \url{http://www.newsforge.com/}
  \item Linux Magazine: \url{http://www.linux-mag.com/}
  \item Linux Today: \url{http://linuxtoday.com/}
  \end{itemize}
\end{itemize}



\section{Info}
\label{sec:info}

\begin{itemize}
\item Many \GNU tools are documented properly using the {\kwd Texinfo}
  system.
\item {\kwd Texinfo} provides two forms of documentation from one
  source:
  \begin{itemize}
  \item online hyperlinked {\kwd info} pages
  \item Nicely formated printed documentation
  \end{itemize}
\item Can read {\kwd info} pages using the {\cmdn info} or
  \texttt{pinfo} commands, or (my choice): {\cmdn emacs}
\end{itemize}

\section{Using the \texttt{info} command}

\begin{itemize}
\item To get information about {\usb command}, type:

{\cmdn \$\ info \usb command}
\item For example, to get information about {\cmdn chmod}, type:
\begin{verbatim}
$ info chmod
\end{verbatim}%$

\item The page has ``cross references'' (like hyperlinks) and menu items.
\item You can press the {\kbk tab} key to select the next cross
  reference, and {\kbk Enter} to go there
\item Go to the \textbf{n}ext page with the {\kbk n} key
\item Go to the \textbf{p}revious page with the {\kbk p} key
\item You can go \textbf{u}p, and visit the \textbf{l}ast page you
  just visited (like the back button on your browser)
\item Get detailed \textbf{h}elp with the {\kbk h} key
\end{itemize}


\section{Using \texttt{emacs} to read \texttt{info} pages}
\label{sec:emacs-info}

\begin{itemize}
\item While running {\cmdn emacs}, you can enter {\kwd info} by
  pressing {\kbk C-h\,i} (That's {\kbk Control-h}, then press
  the key {\kbk i}).
\item You will see a large number of links.  You can search for the
  right topic by:
  \begin{itemize}
  \item pressing {\kbk C-s} and typing the name you are looking for,
    or
  \item go straight to the menu item by pressing \key{m} then the name
    of the menu item.
  \end{itemize}
  
\item press the middle mouse button while the mouse is over a cross
  reference or menu item
  \begin{itemize}
  \item If your mouse only has two buttons, press both buttons at
    once.
  \item If that doesn't work, enable ``Emulate 3 buttons'' in the
    {\cmdn mouseconfig} program, and restart X.
  \end{itemize}
\item There are navigation buttons on the top of {\cmdn emacs}
\end{itemize}


\section{Using \texttt{rpm} to identify all documentation for a
  software package}
\label{sec:rpm}

\begin{itemize}
\item Suppose:
  \begin{itemize}
  \item you want to find the information for the Apache web server,
    \texttt{httpd}
    
  \item You type \texttt{man httpd}; there is no result.
  \item What should you do next?
  \end{itemize}
\item Use the \RPM package manager.
\item The \RPM package manager (\RPM) is a set of programs to manage
  installed software.
\item \RPM maintains a database containing very detailed information
  about all installed software
\item \RPM can:
  \begin{itemize}
  \item list all files in a software package,
  \item list all documentation files in the package,
  \item list all configuration files in the package,
  \item determine if a file has changed since the original
    installation,
  \item verify that a software package is correctly installed,
  \item tell you what RPM package any file comes from,
  \item \ldots and countless other things.
  \end{itemize}
\end{itemize}


\section{A quick guide to \texttt{rpm}}
\label{sec:quick-guide-to-rpm}

\begin{itemize}
\item Here is a brief list of {\cmdn rpm} \textbf{\textit{q}}uery
  commands.  I have used the \texttt{httpd} package as an example.

  \vspace{2ex}

  {\myss 
    \begin{tabularx}{\linewidth}{@{}>{\ttfamily}lY@{}}
      \toprule%
      \textnormal{command} & effect\\
      \midrule%
      rpm -qa \textbar{} less & list all installed software packages\\
      rpm -q httpd & show the version of the httpd package, if it is
      installed \\
      rpm -qa \textbar{} grep httpd & show all installed packages that
      have \emph{httpd} in their name\\
      rpm -ql httpd & \textbf{\textit{l}}ist all files in the httpd package \\
      rpm -qd httpd & list all \textbf{\textit{d}}ocumentation
      files in the httpd package \\
      rpm -qc httpd & list all \textbf{\textit{c}}onfiguration files
      in the httpd
      package \\
      rpm -qi httpd & display \textbf{\textit{i}}nformation about
      the package \\
      rpm -V httpd & \textbf{\textit{v}}erify that the \texttt{httpd}
      package is correctly
      installed\\
      rpm -qf /etc/passwd & determine which package the
      \texttt{/etc/passwd} \textbf{\textit{f}}ile belongs to\\
      \bottomrule
    \end{tabularx}%
    }

  \vspace{2ex}

\item Further information about {\cmdn rpm}:
  \begin{itemize}
  \item \texttt{man rpm}
  \item The chapter on {\cmdn rpm} in the \emph{Red Hat Linux
      Customization Guide}
  \item The book \emph{Maximum RPM}, available in html on the Red Hat
    documentation \CDROM.
  \item It is worth learning how to build \RPM packages.
  \end{itemize}
\end{itemize}

\section{A quick guide to \texttt{dpkg} (on Debian Linux)}
\label{sec:quick-guide-to-dpkg}

\begin{itemize}
\item The Debian Linux distribution is the easiest to upgrade (but not
  so easy to install), thanks to the wonderful \texttt{apt-get}
  command.  For you reference, here is a table comparing some {\cmdn
    rpm} and {\cmdn dpkg} commands:

  \vspace{2ex}

  {\myss 
    \begin{tabularx}{\linewidth}{@{}>{\ttfamily}lY@{}}
      \toprule%
      \textnormal{command} & effect\\
      \midrule%
      dpkg --list \textbar{} less & list all installed software packages\\
      dpkg -l httpd & show the version of the httpd package, if it is
      installed \\
      dpkg --list \textbar{} grep httpd & show all installed packages that
      have \emph{httpd} in their name\\
      dpkg --listfiles httpd & list all files in the httpd package \\
%%       dpkg -qld apache & list all documentation files in the apache package \\
%%       dpkg -qlc apache & list all configuration files in the apache
%%       package \\
      dpkg --print-avail apache & display information about the package \\
%%       dpkg -V apache & verify that the apache package is correctly
%%       installed\\
      dpkg -S /etc/passwd & determine which package the
      \texttt{/etc/passwd} file belongs to\\
      \bottomrule
    \end{tabularx}%
    }

  \vspace{2ex}

\end{itemize}


\section{Browsing Documentation Via Your Web Server}
\label{sec:browsing-docs-httpd}

\begin{itemize}
\item You may configure the web server, {\cmdn apache}, to serve the
  documentation online
\item Two steps may be necessary to achieve this:
  \begin{itemize}
  \item create a file {\fn /etc/httpd/conf.d/doc.conf} containing:
\begin{verbatim}
Alias /doc/ /usr/share/doc/
<Directory /usr/share/doc>
    Options Indexes FollowSymLinks
</Directory>
\end{verbatim}

  \item enable your web server service:
\begin{alltt}
$ \textbf{sudo /sbin/chkconfig httpd on}
$ \textbf{sudo /sbin/service httpd start}
\end{alltt}
  \end{itemize}

\item Now you should be able to browse the documentation in {\fn
    /usr/share/doc} from the \URL:

  http://\meta{ip-address}/doc/
  
  where \meta{ip-address} is the \IP address or \DNS name of your
  computer.
\end{itemize}
{\normalsize


\section{The exercises}

The aim of these exercises is for you to learn how to find helpful
information, not to just sit here reading it now!  The information you
need to do each of these exercises is provided for you in this chapter.

\begin{enumerate}
\item The Linux Documentation Project provides a number of
  \emph{guides}; these are full length, online books.  Locate:
  \begin{enumerate}
  \item a book about network administration

  \item A book about shell programming using \texttt{bash}
  \end{enumerate}

\item Locate the documentation \CDROM image on our server for Red Hat
  9, and determine how to burn a copy of it.
  
\item Go to the location for Red Hat mailing lists, select the
  \texttt{shrike} list, and browse the most recent threaded archive of
  discussion about Red Hat 9.  Subscribe to this list, and set up
  filtering on your mail client, so that the mailing list information
  is kept in a separate mailbox from your normal email.  See
  section~\S\vref{sec:mailing-lists}.

\item Install a copy of the Red Hat documentation onto your computer
  from the network filesytem containing the documentation RPMs,
  and install them.  The last step is to read them!  Here is how:
  \begin{enumerate}
  \item At a prompt, type:
\begin{alltt}
$ \textbf{cd /home/nfs/redhat-9/doc/RedHat/RPMS}
$ \textbf{sudo rpm -Uhv *.rpm}
\end{alltt}
  \item Now view this documentation in your web browser at the
    location: \url{file:///usr/share/doc/} and look for the Red Hat
    ``Getting Started Guide'' under \texttt{rhl-gsg-en-9}.  Click on
    the file \texttt{index.html}.  I
    particularly recommend this book for you to get started with Linux\@.
    
  \item The book \emph{Maximum RPM} under \texttt{maximum-rpm-1.0}
    explains much about how \RPM works.
  \end{enumerate}

\item Visit Alan Cox's ``Portaloo'' (see section
  \vref{sec:online-magazines})
  \begin{enumerate}
  \item add all the channels by clicking on ``Add Everything''
  \item place a bookmark to this site in your browser
  \item Note that each rectangle contains current links to headlines
    on a technical news web site.
  \end{enumerate}

\item Visit the slashdot web site at \url{http://slashdot.org/}
  \begin{enumerate}
  \item Click on a ``Read more \ldots'' link
  \item Change your ``Threshold'' to 3.  This means that you only see
    postings that have a score of 3, 4 or 5.
  \item See whether the discussion is sensible or not!
  \item Slashdot uses a \emph{moderation} system, a voting system,
    where silly posts are ``modded down'', (given a lower score),
    while useful posts are ``modded up'' (are given a higher score).
    This is essential, because anyone can post, and there are enough
    silly people in the world to make Slashdot unusable without such a
    moderation system.
  \end{enumerate}

\item View the on-disk documentation for the \texttt{bash} shell:
  \begin{enumerate}
  \item In the \texttt{man} page
  \item using the \texttt{info bash} command
  \item using the \texttt{pinfo bash} command
  \item using info within emacs
  \end{enumerate}
  
\item Determine the location of the documentation for the
  \texttt{bash} software package using \texttt{rpm}.

\item Determine what software package the file
  \texttt{/usr/lib/libc.so} belongs to, and find its documentation.
\end{enumerate}

\section{Documentation: Solutions}

\includeversion{Solutions}%
\excludeversion{noSolutions}%

\begin{Solutions}
\begin{enumerate}
  \addtocounter{enumi}{6}
\item
  \begin{enumerate}
  \item 
\begin{alltt}
$ \textbf{man bash}      
\end{alltt}%$
  \item 
\begin{alltt}
$ \textbf{info bash}      
\end{alltt}%$
  \item 
\begin{alltt}
$ \textbf{pinfo bash}
bash: pinfo: command not found
$ \textbf{sudo rpm -Uhv /home/nfs/rh-9-updated/RedHat/RPMS/pinfo-0.6.6-4.i386.rpm}
Preparing...                ########################################### [100%]
   1:pinfo                  ########################################### [100%]
$ \textbf{pinfo bash}
\end{alltt}%$
  \item 
\begin{alltt}
$ \textbf{emacs &}
\end{alltt}%$
Then the following keystrokes:
\begin{itemize}
\item \key{Control-h i} (to start the help system)
\item \key{m}\ \ \key{b}\key{a}\key{s}\key{h} (to select the
  \texttt{bash} \textbf{\textit{m}}enu item) 
\end{itemize}
\end{enumerate}

\item
\begin{alltt}
$ \textbf{rpm -qd bash}
/usr/share/doc/bash-2.05b/CHANGES
/usr/share/doc/bash-2.05b/COMPAT
/usr/share/doc/bash-2.05b/FAQ
/usr/share/doc/bash-2.05b/INTRO
\ldots
/usr/share/man/man1/unset.1.gz
/usr/share/man/man1/wait.1.gz
\end{alltt}%$

\item
\begin{alltt}
$ \textbf{rpm -qf /usr/lib/libc.so}
glibc-devel-2.3.2-27.9
$ \textbf{rpm -qd glibc}
/usr/share/info/libc.info-1.gz
/usr/share/info/libc.info-10.gz
/usr/share/info/libc.info-11.gz
\ldots
/usr/share/man/man3/sigwait.3thr.gz
\end{alltt}
This software package contains the main libraries you link with when
you write programs that interact with the operating system.

You can read the info documentation with, well, \texttt{info}:
\begin{alltt}
$ \textbf{info libc}
\end{alltt}%$
\end{enumerate}
\end{Solutions}

\begin{noSolutions}
  We will provide solutions soon.
\end{noSolutions}
\label{endofchapter-documentation}
} % end of normalsize for exercises
} % end of \mns at start of file.

\excludeversion{Solutions}%
\includeversion{noSolutions}%