\input{gl2.slide-header-beamer}%
\errorcontextlines=99
%% Subtopic Number = '1.108.1'
%% Title from filename: 'Use and manage local system documentation'
%% Weight: 4
%% Description:
%% %% Key files, terms, and utilities include:
%%        MANPATH man
%%        apropos
%%        whatis
\title{1.108.1\\Use and manage local system documentation\\Weight 4}
\author[Geoffrey Robertson]{Geoffrey Robertson \texttt{ge@ffrey.com}
  \and Nick Urbanik
  \texttt{nicku@nicku.org}\\
  {\tiny This document Licensed under GPL---see
    section~\ref{sec:license}}}%
\subtitle{Linux Professional Institute Certification --- 102}%
\mode<article>{\chead{1.108.1}}%

% TODO Nick:

% Look for additional things in my Documentation notes that may be
% helpful here.


\begin{document}
\maketitle
\mode<article>{\thispagestyle{empty}}


\begin{frame}
  \frametitle{Outline}
  \mode<presentation>
  {%
    %\footnotesize
    \begin{multicols}{2}
      \tableofcontents
    \end{multicols}
    % You might wish to add the option [pausesections]
  }%
  \mode<article>
  {%
    \tableofcontents
  }%
\end{frame}

\section{Context}
\label{sec:context}

\begin{frame}
  \frametitle{Topic 108 Documentation [8]}%
  \framesubtitle{Where we are up to}%
    \begin{description}
    % \uline depends on \usepackage[normalem]{ulem}:
    \item[1.108.1] \textbf{\uline{Use and manage local system documentation [4]}}
    \item[1.108.2] Find Linux documentation on the Internet [3]
    \item[1.108.5] Notify users on system-related issues [1]
    \end{description}
\end{frame}

 
%==============================================================================

\section{Objective}
\label{sec:objective}

\begin{frame}
  \frametitle{Use and Manage Local System Documentation}%
  \framesubtitle{Objective}%
  \mode<presentation>{\Large}%
  Candidates should be able to use and administer the \texttt{man}
  facility and the material in \texttt{/usr/share/doc/}.
  \par
  This objective includes finding relevant \texttt{man} pages,
  searching \texttt{man} page sections, finding commands and
  \texttt{man} pages related to them, and configuring access to
  \texttt{man} sources and the \texttt{man} system.
  \par
  It also includes using system documentation stored in
  \path{/usr/share/doc/} and determining what documentation to keep in
  \path{/usr/share/doc/}.
\end{frame}

\begin{frame}
  \frametitle{Use and Manage Local System Documentation}%
  \framesubtitle{Key files, terms, and utilities}%
  \mode<presentation>{\large}%
  \begin{description}
  \item[\texttt{MANPATH}] --- an environment variable that specifies
      a search path for \texttt{man} pages
  \item[\texttt{man}] --- the program that accesses \texttt{man} pages
  \item[\texttt{apropos}] --- searches descriptions of \texttt{man}
      pages, returning all matches; same as \texttt{man~-k}
  \item[\texttt{whatis}] --- returns descriptions of matching \texttt{man}
      page; same as \texttt{man~-f}
  \end{description}
\end{frame}

%-----------------------------------------------------------
 
%==============================================================================
% \begin{frame}[fragile]
% \frametitle{Use and Manage Local System Documentation}
% \framesubtitle{Resources}
% \begin{semiverbatim}

% \end{semiverbatim}
% \end{frame}

%-----------------------------------------------------------
 
%==============================================================================

\section{\texttt{whatis} and \texttt{apropos}}
\label{sec:whatis-and-appropos}

\subsection{\texttt{whatis}}
\label{sec:whatis}

\begin{frame}[fragile]
  \frametitle{Using \texttt{whatis}}%
  \framesubtitle{display manual page descriptions}%
  \begin{itemize}
  \item \texttt{whatis} searches the manual page names and displays
    the manual page descriptions of any name matched.
    % \pause 
    % \overlay{2}
    \pause
  \item 
\begin{semiverbatim}
\cmd{whatis nmap}
nmap   (1)  - Network exploration tool 
              and security scanner
\end{semiverbatim}
    %\overlay{3}
    \pause%
\item (in Debian and Ubuntu but not Red Hat/Fedora)
\begin{semiverbatim}
-r, -{}-regex    Interpret each name as 
               a regular expression. 
\cmd{whatis -r ^ifc}
ifconfig (8)   - configure a network interface 
\end{semiverbatim}
    \pause%
  \item Is equivalent to
    \par
    \cmd{man -f}
  \item This may have been asked in previous exams
  \item Nick's silly mnemonic: What the \texttt{\textbf{-f}\ldots}
    is\ldots
  \end{itemize}
\end{frame}

%-----------------------------------------------------------


 
%==============================================================================

\subsection{\texttt{apropos}}
\label{sec:apropos}


%==============================================================================
\begin{frame}[fragile]
  \frametitle{Using \texttt{apropos}}%
  \framesubtitle{search the manual page names and descriptions}%
  Each manual page has a short description available within it.
  \texttt{apropos} searches the descriptions for instances of keyword.
  % \overlay{1}
  \pause%
    {\mode<presentation>{\scriptsize}\mode<article>{\small}%
\begin{semiverbatim}
\cmd{apropos nmap}
mmap (2)             - map or unmap files or devices into memory
munmap (2)           - map or unmap files or devices into memory
nmap (1)             - Network exploration tool and security scanner
Tk_MapWindow (3tk)   - map or unmap a window
...
\end{semiverbatim}%
    }
  \pause%
  \begin{itemize}
  \item Is equivalent to
    \par
    \cmd{man -k}
  \item This may have been asked in previous exams
  \item Nick's silly mnemonic: apropos \textbf{\texttt{-k}}an produce
    many lines of output
  \end{itemize}
\end{frame}

\subsection{Building \texttt{whatis}/\texttt{appropos} database}
\label{sec:makewhatis}



\begin{frame}
  \frametitle{Database for \texttt{whatis} and \texttt{appropos}}
  \begin{itemize}
  \item Both texttt{whatis} and \texttt{appropos} use a common simple
    text file database
  \item Built by a nightly \texttt{cron} job script in
    \path{/etc/cron.daily}
  \item Red Hat/Fedora runs a shell script \path{/usr/sbin/makewhatis}
  \item Ubuntu runs a program \path{/usr/bin/mandb}
  \end{itemize}
\end{frame}

\section{\texttt{man}}
\label{sec:man}

\begin{frame}[fragile]
\frametitle{Using \texttt{man}}
\mode<presentation>{\scriptsize}%
\mode<article>{\small}
\begin{semiverbatim}
\cmd{man man}
man(1)                                                                  man(1)

NAME
       man - format and display the on-line manual pages
       manpath - determine user's search path for man pages

SYNOPSIS
       man  [-acdfFhkKtwW]  [-{}-path]  [-m system] [-p string]
       [-C config_file] [-M pathlist] [-P pager] [-S section_list]
       [section] name ...

DESCRIPTION
       man formats and displays the on-line manual pages.
\end{semiverbatim}
\end{frame}

\subsection{\texttt{man} options}
\label{sec:man-options}

\begin{frame}
  \frametitle{Using \texttt{man}}%
  \framesubtitle{options}%
  \begin{description}
  \item[\texttt{\textbf{-k}}] Equivalent to \texttt{apropos}
  \item[\texttt{\textbf{-f}}] Equivalent to \texttt{whatis}
  \item[\texttt{\textbf{-K}}] Search for the specified string in \alert{all} man pages.
    Warning: this is probably very slow!  It helps to specify a section.
    (Just to give a rough idea, on my machine this takes about a minute
    per 500 man pages.)
  \item[\texttt{\textbf{-a}}] Show all matching man pages from all
    sections; for example, \texttt{man -a passwd} shows the man pages
    both for \texttt{passwd(1)} and \texttt{passwd(5)}.
  \end{description}
\end{frame}

\subsection{\texttt{man} --- configuring}
\label{sec:man-configuring}

\begin{frame}[fragile]
  \frametitle{Configuring how man finds manpages}
  \begin{itemize}
  \item The configuration file for man is:
    \begin{itemize}
    \item Red Hat/Fedora sytems: \texttt{/etc/man.config}
    \item Ubuntu: \texttt{/etc/manpath.config}
    \end{itemize}
  \item can override the search paths specified in the configuration
    files using the \red{\texttt{MANPATH}} environment variable
    \begin{itemize}
    \item \texttt{MANPATH} is a colon-separated list of directories to search
    \end{itemize}
  \item You can see the existing search path with\\
    \cmd{man -{}-path}\\
    or:
\begin{semiverbatim}
\cmd{manpath}\scriptsize
/usr/local/man:/usr/local/share/man:/usr/share/man:/usr/X11R6/man
\end{semiverbatim}
% \mode<presentation>{
% \begin{semiverbatim}
% \cmd{manpath}\scriptsize
% /usr/local/man:/usr/local/share/man:/usr/share/man:/usr/X11R6/man
% \end{semiverbatim}
% }\mode<article>{
% \begin{semiverbatim}
% \cmd{manpath}\footnotesize
% /usr/local/man:/usr/local/share/man:/usr/share/man:/usr/X11R6/man
% \end{semiverbatim}
% }
  \end{itemize}
\end{frame}

%==============================================================================

\subsection{\texttt{man} section numbers}
\label{sec:man-section-numbers}

%==============================================================================
\begin{frame}
  \frametitle{The Manual Section Numbers}
  \begin{enumerate}
  \item \alert{Executable programs} or shell commands
  \item System calls (functions provided by the kernel)
  \item Library calls (functions within system libraries)
  \item Special files (usually found in \texttt{/dev})
  \item \alert{File formats and conventions} eg \texttt{/etc/passwd}
  \item Games
  \item Miscellaneous (including macro packages and conventions), e.g.
    \texttt{man(7)}, \texttt{groff(7)}
  \item \alert{System administration commands} (usually only for root)
  \item Kernel routines [Non standard]
  \end{enumerate}
\end{frame}

\begin{frame}
  \frametitle{Navigating in \texttt{man} (really \texttt{less})}%
  The \texttt{man} program actually calls many other programs,
  displaying the result, by default, with the \texttt{less} program:\\{\mode<presentation>{\footnotesize}
  \cmd{man -d man 2>\&1 | tail -n 1}\\
  \texttt{(cd /usr/share/man/en \&\& (echo ".pl 11i"; /usr/bin/gunzip -c '/usr/share/man/en/man1/man.1.gz') | /usr/bin/gtbl | /usr/bin/nroff -c --legacy ISO-8859-1 -mandoc 2>/dev/null | /usr/bin/less -is)}}

  \begin{description}
  \item[h] Show detailed help on using the \texttt{less} program
  \item[q] Quit
  \item[g] Go to beginning of \texttt{man} page
  \item[G] Go to end of \texttt{man} page
  \item[/string] Search for string.
  \item[n] repeat previous search forwards
  \item[?string] Search for string backwards
  \item[N] repeat previous search backwards
  \item[ESC-u] Undo (toggle) search highlighting.
  \end{description}
\end{frame}

%==============================================================================

\section{GNU \texttt{info}}
\label{sec:info}


%==============================================================================
\begin{frame}[fragile]
\frametitle{GNU \texttt{info}}
{\mode<article>{\footnotesize}
\mode<presentation>{\scriptsize}
\begin{semiverbatim}
File: info.info,  Node: Top,  Next: Getting Started,  Up: (dir)

Info: An Introduction
*********************

The GNU Project distributes most of its on-line manuals in the "Info
format", which you read using an "Info reader".  You are probably using
an Info reader to read this now.

   There are two primary Info readers: `info', a stand-alone program
designed just to read Info files, and the `info' package in GNU Emacs,
a general-purpose editor.  At present, only the Emacs reader supports
using a mouse.

   If you are new to the Info reader and want to learn how to use it,
type the command `h' now.  It brings you to a programmed instruction
sequence.

   To read about expert-level Info commands, type `n' twice.  This
brings you to `Info for Experts', skipping over the `Getting Started'
chapter.

* Menu:

* Getting Started::        Getting started using an Info reader.
* Expert Info::            Info commands for experts.
* Creating an Info File::  How to make your own Info file.
* Index::                  An index of topics, commands, and variables.
--zz-Info: (info.info.gz)Top, 29 lines --Top-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-{}-------------------------
Welcome to Info version 4.8. Type ? for help, m for menu item.
\end{semiverbatim}
}
\end{frame}


%-----------------------------------------------------------

%==============================================================================

\subsection{Navigation in info}
\label{sec:info-navigation}


%==============================================================================
\begin{frame}
  \frametitle{GNU \texttt{info} Navigation}
  \begin{description}
  \item[Tab] Move among hyperlinks
  \item[Enter] Follow hyperlinks
  \item[d] Return to the top
  \item[?] List these info commands
  \item[n] Move to the "next" node of this node.
  \item[p] Move to the "previous" node of this node.
  \item[u] Move "up" from this node.
  \item[q] Quit Info altogether.
  \item[h] Show a primer for first time users.
  \item[/string] Search for string.
  \end{description}
\end{frame}


%-----------------------------------------------------------

%==============================================================================

\section{\texttt{/usr/share/doc}}
\label{sec:/usr/share/doc}


%==============================================================================
\begin{frame}[fragile]
\frametitle{\texttt{/usr/share/doc/}}%
General information about packages and programs.
\begin{semiverbatim}
\cmd{ls /usr/share/doc/}
a2ps-4.13b                 macutils-2.0b3
a52dec-0.7.4               Maelstrom-3.0.6
aalib-1.4.0                MagicPoint-1.11b
abiword-2.4.1              mailman-2.1.5
abook-0.5.4                make-3.80
ac-archive-0.5.39          MAKEDEV-3.19
acl-2.2.23                 man-pages-1.67
adjtimex-1.20              man-pages-cs-0.16
aiksaurus-1.2.1            man-pages-da-0.1.1
alchemist-1.0.36           man-pages-de-0.4
alchemist-devel-1.0.36     man-pages-es-1.28
alsa-lib-1.0.9rf           man-pages-fr-0.9.7
\end{semiverbatim}
\end{frame}

%-----------------------------------------------------------

%==============================================================================
%==============================================================================
\begin{frame}[fragile]
\frametitle{\texttt{/usr/share/doc/}}
\begin{semiverbatim}
\cmd{ls /usr/share/doc/acl-2.2.23}
CHANGES.gz  LICENSE  PORTING  README
\end{semiverbatim}
\end{frame}

%-----------------------------------------------------------

%==============================================================================
%==============================================================================
\begin{frame}[fragile]
\frametitle{\texttt{/usr/share/doc/}}
\mode<presentation>{\scriptsize}
\begin{semiverbatim}
\cmd{head /usr/share/doc/acl-2.2.23/README}
Access control list package README
__________________________________

See the file doc/INSTALL for build, installation and post-
install configuration steps.

Refer to the acl(5) manual page for general access control list
information and references to other related manual pages.

The extended attributes and access control list project for the
ext2 and ext3 filesystems is located at:
        http://acl.bestbits.at/

For more information and details on how to contribute to the
XFS project see the web pages at:
        http://oss.sgi.com/projects/xfs/
\end{semiverbatim}
\end{frame}

%-----------------------------------------------------------

%==============================================================================
%==============================================================================
\begin{frame}[fragile]
  \frametitle{\texttt{/usr/share/doc/}}%
  \makebox[0.8\width][l]{\cmd{firefox /usr/share/doc/xfig/html/index.html}}
  \par\bigskip\par
  \ldots\,or open this file URL:
  \par\bigskip\par
  \url{file:///usr/share/doc/xfig/html/index.html}
\end{frame}


%-----------------------------------------------------------

%==============================================================================
% \begin{frame}
% \frametitle{The End}
% \end{frame}

%-----------------------------------------------------------


\mode<presentation>
{%
\begin{frame}
  \frametitle{Topics Covered}
  %\footnotesize
  %\begin{multicols}{2}
    \tableofcontents[pausesections,pausesubsections]
  %\end{multicols}
  % You might wish to add the option [pausesections]
\end{frame}
}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


\section{License Of This Document}
\label{sec:license}
%Angus Lees
%  <gus@inodes.org>, 

\begin{frame}
  \frametitle{License Of This Document}%
  \raggedright%
  Copyright \copyright\ 2005, 2003 Geoffrey Robertson <ge@ffrey.com>
  and Nick Urbanik <nicku@nicku.org>.
  \par
  Permission is granted to make and distribute verbatim copies or
  modified versions of this document provided that this copyright
  notice and this permission notice are preserved on all copies under
  the terms of the GNU General Public License as published by the Free
  Software Foundation---either version 2 of the License or (at your
  option) any later version.
\end{frame}
\end{document}