[gentoo-doc-cvs] cvs commit: info-guide.xml man-guide.xml metadoc.xml

[Xavier Neys]

neysx       06/05/27 14:35:25

  Modified:             metadoc.xml
  Added:                info-guide.xml man-guide.xml
  Log:
  #127954 & #127826 new {info,man}\guide.ml docs

Revision  Changes    Path
1.152                xml/htdocs/doc/en/metadoc.xml

file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/metadoc.xml?rev=1.152&content-type=text/x-cvsweb-markup&cvsroot=gentoo
plain: http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/metadoc.xml?rev=1.152&content-type=text/plain&cvsroot=gentoo
diff : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/metadoc.xml.diff?r1=1.151&r2=1.152&cvsroot=gentoo

Index: metadoc.xml
===================================================================
RCS file: /var/cvsroot/gentoo/xml/htdocs/doc/en/metadoc.xml,v
retrieving revision 1.151
retrieving revision 1.152
diff -u -r1.151 -r1.152
--- metadoc.xml	1 May 2006 17:06:16 -0000	1.151
+++ metadoc.xml	27 May 2006 14:35:25 -0000	1.152
@@ -1,9 +1,9 @@
 <?xml version='1.0' encoding="UTF-8"?>
-<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/metadoc.xml,v 1.151 2006/05/01 17:06:16 neysx Exp $ -->
+<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/metadoc.xml,v 1.152 2006/05/27 14:35:25 neysx Exp $ -->
 <!DOCTYPE metadoc SYSTEM "/dtd/metadoc.dtd">
 
 <metadoc lang="en">
-<version>1.79</version>
+<version>1.81</version>
   <members>
     <lead>neysx</lead>
     <member>fox2mike</member>
@@ -267,6 +267,7 @@
     <file id="source_mirrors">/doc/en/source_mirrors.xml</file>
     <file id="gentoo-ppc-install">/doc/en/gentoo-ppc-install.xml</file>
     <file id="gentoo-x86-quickinstall">/doc/en/gentoo-x86-quickinstall.xml</file>
+    <file id="gentoo-x86-quickinstall+raid">/doc/en/gentoo-x86+raid+lvm2-quickinstall.xml</file>
     <file id="vi-guide">/doc/en/vi-guide.xml</file>
     <file id="virt-mail-howto">/doc/en/virt-mail-howto.xml</file>
     <file id="mailfilter-guide">/doc/en/mailfilter-guide.xml</file>
@@ -392,6 +393,8 @@
     <file id="jffnms">/doc/en/jffnms.xml</file>
     <file id="conky">/doc/en/conky-howto.xml</file>
     <file id="ldapdns">/doc/en/ldapdns-guide.xml</file>
+    <file id="man-guide">/doc/en/man-guide.xml</file>
+    <file id="info-guide">/doc/en/info-guide.xml</file>
   </files>
   <docs>
     <doc id="name-logo">
@@ -615,6 +618,10 @@
       <memberof>install_guides</memberof>
       <fileid>gentoo-x86-quickinstall</fileid>
     </doc>
+    <doc id="gentoo-x86-quickinstall+raid">
+      <memberof>install_guides</memberof>
+      <fileid>gentoo-x86-quickinstall+raid</fileid>
+    </doc>
     <doc id="gentoo-sparc-quickinstall">
       <memberof>install_guides</memberof>
       <fileid>gentoo-sparc-quickinstall</fileid>
@@ -1253,5 +1260,13 @@
       <memberof>sysadmin_specific</memberof>
       <fileid>ldapdns</fileid>
     </doc>
+    <doc id="man-guide">
+      <memberof>sysadmin_general</memberof>
+      <fileid>man-guide</fileid>
+    </doc>
+    <doc id="info-guide">
+      <memberof>sysadmin_general</memberof>
+      <fileid>info-guide</fileid>
+    </doc>
   </docs>
 </metadoc>



1.1                  xml/htdocs/doc/en/info-guide.xml

file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/info-guide.xml?rev=1.1&content-type=text/x-cvsweb-markup&cvsroot=gentoo
plain: http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/info-guide.xml?rev=1.1&content-type=text/plain&cvsroot=gentoo

Index: info-guide.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/info-guide.xml,v 1.1 2006/05/27 14:35:25 neysx Exp $ -->

<guide link="/doc/en/info-guide.xml" lang="en">
<title>Gentoo Info Guide</title>

<author title="Chris White">
  <mail link="chriswhite@g.o">Chris White</mail>
</author>

<abstract>
This guide is meant to show how to navigate info pages using the info command.
</abstract>

<!-- The content of this document is licensed under the CC-BY-SA license -->
<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
<license/>

<version>1</version>
<date>2006-03-28</date>

<chapter>
<title>Introduction</title>
<section>
<title>What is info?</title>
<body>

<p>
Most of you may be familiar with the <c>man</c> documentation system. While man
is good with quickly looking up items, it lacks structure in linking man pages
together. This is where <c>info</c> comes in. Info pages are made using the
<c>texinfo</c> tools, and can link with other pages, create menus and ease
navigation in general. The next section will look at how info pages are laid
out.
</p>

</body>
</section>
<section>
<title>Info pages layout</title>
<body>

<p>
The main info pages are held in <path>/usr/share/info</path>. Unlike the man
style directory layout, <path>/usr/share/info</path> contains what is largely a
rather extensive collection of files. These files have the following format:
</p>

<pre caption="info file format">
pagename.info[-node].gz
</pre>

<p>
<c>pagename</c> is the actual name of the page (example: <c>wget</c>).
<c>[-node]</c> is an optional construct that designates another node level
(generally these are referenced to by the toplevel of the info document in
question). In order to save space these info pages are compressed using the
<c>gzip</c> compression scheme. Additional info pages can be listed with the
<c>INFOPATH</c> environment variable (usually set through the various
<path>/etc/env.d/</path> files). To get started, it's important to note the
<path>/usr/share/info/dir</path> file. This special file is used when info is
ran with no parameters. It contains a listing of all info pages available for
users to browse. To begin looking at navigating around in info, we'll go ahead
and bring it up with no arguments:
</p>

<pre caption="Starting up info">
$ <i>info</i>
</pre>

<p>
Now in the next chapter we'll look at dealing with basic info navigation.
</p>

</body>
</section>
</chapter>
<chapter>
<title>Working with info pages</title>
<section>
<title>Browsing with menus</title>
<body>

<p>
Now that info is started, we're given a screen similar to this:
</p>

<pre caption="Sample info screen">
File: dir,      Node: Top       This is the top of the INFO tree

  This (the Directory node) gives a menu of major topics.
  Typing "q" exits, "?" lists all Info commands, "d" returns here,
  "h" gives a primer for first-timers,
  "mEmacs&lt;Return&gt;" visits the Emacs manual, etc.

  In Emacs, you can click mouse button 2 on a menu item or cross reference
  to select it.

* Menu:

User Interface Toolkit
* GDK: (gdk).           The General Drawing Kit
* GTK: (gtk).           The GIMP Toolkit

GNU programming tools
* Autoconf v2.1: (autoconf).         Create source code configuration scripts.
</pre>

<p>
Right now there are a bunch of entries with an asterisk before them. These are
menu items for navigating through different node levels. There are two ways of
selecting menus. We'll look at the first now and the other way later. First
off, we'll go ahead and look at the <c>wget</c> info page. To do so, use the
down error key until you reach the area indicated by the blue highlighting:
</p>

<pre caption="Navigating to the wget info menu entry">
Network Applications
* GnuTLS: (gnutls).                     Package for Transport Layer Security.
* <i>Wget: (wget).</i>         The non-interactive network downloader.
* certtool: (gnutls)Invoking certtool.  Manipulate certificates and keys.
* gnutls-cli: (gnutls)Invoking gnutls-cli.      GNU TLS test client.
* gnutls-cli-debug: (gnutls)Invoking gnutls-cli-debug.  GNU TLS debug client.
* gnutls-serv: (gnutls)Invoking gnutls-serv.    GNU TLS test server.
* srptool: (gnutls)Invoking srptool.    Simple SRP password tool.
</pre>

<p>
Once you get to this area, hit the <c>ENTER</c> key to select the menu item.
This will bring up the info page for <c>wget</c>:
</p>

<pre caption="The wget info page">
File: wget.info,  Node: Top,  Next: Overview,  Up: (dir)

Wget 1.10.2
***********

This manual documents version 1.10.2 of GNU Wget, the freely available
utility for network downloads.

   Copyright (C) 1996-2005 Free Software Foundation, Inc.

* Menu:

* Overview::            Features of Wget.
* Invoking::            Wget command-line arguments.
* Recursive Download::  Downloading interlinked pages.
* Following Links::     The available methods of chasing links.
* Time-Stamping::       Mirroring according to time-stamps.
* Startup File::        Wget's initialization file.
</pre>

<p>
Now that we have an info page up, the next section will look at basic
navigation.
</p>

</body>
</section>
<section>
<title>Basic navigation</title>
<body>

<p>
In terms of nodes, this is considered the <c>Top</c> node for the wget page.
Consider the <c>Top</c> node to be the same as the table of contents for that
particular info page. Now to navigate the actual page itself, you have a couple
of different methods. First off is the standard info method. This is using the
<c>SPACE</c> key to move forward a page and the <c>BACKSPACE/DELETE</c> keys to
move back a page. This is the recommended method as it automatically
advances/retreats to the appropriate node in the document. This allows for a
somewhat linear browsing for those used to man pages. Another way is through
the <c>PAGE UP/PAGE DOWN</c> keys. These work, but they will not
advance/retreat like <c>SPACE/BACKSPACE/DELETE</c> will. If you want to skip
entire nodes without using <c>SPACE/BACKSPACE/DELETE</c>, you can also use the
<c>[</c> (advance backwards) and <c>]</c> (advance forwards) keys.
</p>

<p>
As mentioned earlier, there are 2 ways of navigating menus. The other way will
now be described here. The numbers <c>1-9</c> can be used to reference to the
first-ninth menu entries in a document. This can be used to quickly peruse
through documents. For example, we'll use <c>3</c> to reach the <c>Recursive
Download</c> menu entry. So press <c>3</c> and it will bring up the
<c>Recursive Download</c> screen:
</p>

<pre caption="Resulting Recursive Download screen">
File: wget.info,  Node: Recursive Download,  Next: Following Links,  Prev: Invoking,  Up: Top

3 Recursive Download
********************

GNU Wget is capable of traversing parts of the Web (or a single HTTP or
FTP server), following links and directory structure.  We refer to this
as to "recursive retrieval", or "recursion".
</pre>

<p>
Now we're at the <c>Recursive Download</c> screen. Here is a good time to note
a few things. First off the top header section. This header shows the
navigation capable from this particular screen. The page indicated by
<c>Next: </c> can be accessed by pressing the <c>n</c> key, and the page
indicated by <c>Prev: </c> can be accessed by pressing the <c>p</c> key. Please
note that this will only work for the same level. If overused you could round
up in totally unrelated content. It's better to use
<c>SPACE/BACKSPACE/DELETE/[/]</c> to navigate in a linear fashion.
</p>

<p>
If for some reason you get lost, there are a few ways to get out. First is the
<c>t</c> key. This will take you straight to the toplevel (table of contents)
for the particular info page you're browsing. If you want to return to the last
page you looked out, you can do so with the <c>l</c> key. If you want to go to
the above level, you can do so with the <c>u</c> key. Now that you have some
idea of navigating a page, the next chapter will look at searching for content.
</p>

</body>
</section>
</chapter>

<chapter>
<title>Searching through info</title>
<section>
<title>Navigating to other info pages</title>
<body>

<p>
Now that you can navigate an individual info page, it's important to look at
accessing other info pages. The first obvious way is to go to the info page
through the <c>dir</c> index listing of info pages. To get to the <c>dir</c>
index from deep within a document, simply press the <c>d</c> key. From there
you can search for the appropriate page you want. However, if you know the
actual page, there is an easier way through the <c>Goto node (g key)</c> command.
To go to an info page by name, type <c>g</c> to bring up the prompt and enter the
name of the page in parentheses:
</p>

<pre caption="Going to an info page by name">
* Startup File::        Wget's initialization file.
* Examples::            Examples of usage.
* Various::             The stuff that doesn't fit anywhere else.
* Appendices::          Some useful references.
* Copying::             You may give out copies of Wget and of this manual.
--zz-Info: (wget.info.gz)Top, 24 lines --Top-------------------------------
Goto node: <i>(libc)</i>
</pre>

<p>
This will bring up the libc page as shown here:
</p>

<pre caption="Result of the Goto node command">
File: libc.info,  Node: Top,  Next: Introduction,  Prev: (dir),  Up: (dir)

Main Menu
*********

This is Edition 0.10, last updated 2001-07-06, of `The GNU C Library
Reference Manual', for Version 2.3.x of the GNU C Library.

* Menu:

* Introduction::                 Purpose of the GNU C Library.
</pre>

<p>
Now that we know how to go to info pages by name, the next section will look at
searching for pieces of information using the info page's index.
</p>

</body>
</section>
<section>
<title>Searching using an index</title>
<body>

<p>
In this example we'll see how to lookup the <c>printf</c> function of the c
library using the <c>libc</c> info page's index. You should still be at the
libc info page from the last section, and if not, use the Goto node command to
do so. To utilize the index search, hit the <c>i</c> key to bring up the
prompt, then enter your search term. We'll do so for <c>printf</c> below:
</p>

<pre caption="Entering an index search query">
* Character Set Handling::       Support for extended character sets.
* Locales::                      The country and language can affect the
                                   behavior of library functions.
* Message Translation::          How to make the program speak the user's
                                   language.
--zz-Info: (libc.info.gz)Top, 1291 lines --Top-- Subfile: libc.info-1.gz-----
Index entry: <i>printf</i>
</pre>

<p>
After pressing enter upon completion of our query, we're brought to the
<c>libc</c> definition for <c>printf</c>:
</p>

<pre caption="Result of the index search query">
File: libc.info,  Node: Formatted Output Functions,  Next: Dynamic Output,  Prev: Other Output Conversions,  Up: Formatted Output

12.12.7 Formatted Output Functions
----------------------------------

This section describes how to call <i>`printf'</i> and related functions.
Prototypes for these functions are in the header file `stdio.h'.
Because these functions take a variable number of arguments, you _must_
declare prototypes for them before using them.  Of course, the easiest
way to make sure you have all the right prototypes is to just include
</pre>

<p>
We've now successfully performed a search using the <c>libc</c> info page
index. However, sometimes what we want is in the page itself. The next section
will look at performing searches within the page.
</p>

</body>
</section>
<section>
<title>Searching using the search command</title>
<body>

<p>
Starting from the previous location at the <c>Formatted Output Functions</c>
node, we'll look at searching for the <c>sprintf</c> variation of the
<c>printf</c> function. To perform a search, press the <c>s</c> key to
bring up the search prompt, and then enter the query (sprintf in this case):
</p>

<pre caption="Entering a search query">
 -- Function: int wprintf (const wchar_t *TEMPLATE, ...)
     The `wprintf' function prints the optional arguments under the
     control of the wide template string TEMPLATE to the stream
     `stdout'.  It returns the number of wide characters printed, or a
--zz-Info: (libc.info.gz)Formatted Output Functions, 127 lines --Top-- Subfile: libc.info-3.gz--
Search for string []: <i>sprintf</i>
</pre>

<p>
Hit <c>ENTER</c> and it will show the result of the query:
</p>

<pre caption="Result of the search query">
-- Function: int <i>sprintf</i> (char *S, const char *TEMPLATE, ...)
     This is like `printf', except that the output is stored in the
     character array S instead of written to a stream.  A null
     character is written to mark the end of the string.

     The `sprintf' function returns the number of characters stored in
     the array S, not including the terminating null character.
</pre>

<p>
And we have the function we need.
</p>

</body>
</section>
</chapter>

<chapter>
<title>Conclusion</title>
<section>
<title>Conclusion</title>
<body>

<p>
This concludes the overview of using info to view info pages. As always
comments are both welcome and appreciated. Clicking on the my name (Chris
White) on the right side will send me an email. 
</p>

</body>
</section>
<section>
<title>Additional Program Resources</title>
<body>

<p>
In order to make things easier for those that wish to browse info pages through
a more friendly graphical interface, the following are available:
</p>

<ul>
  <li>app-text/info2html - Convert info pages to a browse-able HTML format</li>
  <li>app-text/pinfo - <c>ncurses</c> based info viewer</li>
  <li>app-text/tkinfo - a <c>tcl/tk</c> based info browser</li>
  <li>app-vim/info - a <c>vim</c> based info browser</li>
</ul>

<p>
The <c>KDE</c> browser <c>Konqueror</c> also allows you to browse info pages
through the <c>info: </c> URI.
</p>

</body>
</section>
</chapter>
</guide>



1.1                  xml/htdocs/doc/en/man-guide.xml

file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/man-guide.xml?rev=1.1&content-type=text/x-cvsweb-markup&cvsroot=gentoo
plain: http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/man-guide.xml?rev=1.1&content-type=text/plain&cvsroot=gentoo

Index: man-guide.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/man-guide.xml,v 1.1 2006/05/27 14:35:25 neysx Exp $ -->

<guide link="/doc/en/man-guide.xml" lang="en">
<title>Gentoo Man Guide</title>

<author title="Author">
  <mail link="chriswhite@g.o">Chris White</mail>
</author>

<abstract>
This guide shows how to navigate man pages using man.
</abstract>

<!-- The content of this document is licensed under the CC-BY-SA license -->
<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
<license/>

<version>1</version>
<date>2005-03-27</date>

<chapter>
<title>Introduction</title>
<section>
<title>The man program</title>
<body>

<p>
Everyone at some point in their linux life has used it. "It" is the <c>man</c>
command. However, while the man program itself appears to be rather simplistic
in its construct, it has a few extra abilities than just simply scrolling
through the page. This document hopes to achieve shedding some light on these
capabilities.
</p>

</body>
</section>
<section>
<title>Man layout</title>
<body>

<p>
Man pages are mainly stored in the <path>/usr/share/man</path> directory.
However, as long as a man page is located in the <c>MANPATH</c> environment
variable, man will be able to pick it up. Gentoo will generally store
<c>MANPATH</c> variables in <path>/etc/env.d</path>. Within these directories
are some folders with the structure manX where X is the section number. For
example, a standard man layout might look like so:
</p>

<pre caption="Standard man structure">
$ <i>ls /usr/share/man | grep man</i>
man0p
man1
man1p
man2
man3
man3p
man4
man5
man6
man7
man8
man9
mann
</pre>

<p>
The actual section numbering appears fairly standard. However, notice that
there is a <path>mann</path> and some <path>man#p</path> folders. The following
table lists the above man page directories and what is contained within them:
</p>

<table>
<tr>
  <th>Man Directory</th>
  <th>Description</th>
</tr>
<tr>
  <ti>man0p</ti>
  <ti>
    The <c>p</c> here stands for POSIX, as with the other directories with p in
    their names. Man pages in this directory describe the functionality of
    various POSIX header files.
  </ti>
</tr>
<tr>
  <ti>man1</ti>
  <ti>
    This section is for standard commands. Most programs will put their man
    pages here, so this section tends to be the largest.
  </ti>
</tr>
<tr>
  <ti>man1p</ti>
  <ti>
    This section describes the POSIX versions of the commands described in 1p.
    Since it only describes basic commands, it is much smaller than man1.
  </ti>
</tr>
<tr>
  <ti>man2</ti>
  <ti>This section describes Linux kernel system calls.</ti>
</tr>
<tr>
  <ti>man3</ti>
  <ti>This section describes standard c library functions.</ti>
</tr>
<tr>
  <ti>man4</ti>
  <ti>
    This section describes special devices. These devices are generally kernel
    oriented, but <c>Xorg-X11</c> has entries in here as well.
  </ti>
</tr>
<tr>
  <ti>man5</ti>
  <ti>
    This section describes both the makeup of certain files and what files a
    program uses. Those of you reading this document may be familiar with
    references to <c>man 5 portage</c> for a description of the <c>portage</c>
    file structure, and <c>man 5 make.conf</c> for <path>make.con</path>
    makeup.
  </ti>
</tr>
<tr>
  <ti>man6</ti>
  <ti>This section introduces games and other special toys.</ti>
</tr>
<tr>
  <ti>man7</ti>
  <ti>
    This section describes standards and other miscellaneous items. These
    standards can include things such as charsets, SQL statements, ISO
    standards and regular expressions.
  </ti>
</tr>
<tr>
  <ti>man8</ti>
  <ti>
    This section describes administrative commands (those usually run by the
    root user).
  </ti>
</tr>
<tr>
  <ti>man9</ti>
  <ti>
    This section is somewhat sparse, but is meant to contain documentation for
    various parts of the kernel.
  </ti>
</tr>
<tr>
  <ti>mann</ti>
  <ti>
    This section is mainly used by <c>Tcl/Tk</c>. The <c>n</c> stands for new.
  </ti>
</tr>
</table>

<p>
While this is not an extensive and detailed list, it does cover the man pages
that most people will be interested in. However, sometimes you can find out
what a section does as easily as looking at this table. The next chapter will
look at using man to traverse this layout.
</p>

</body>
</section>
</chapter>

<chapter>
<title>Working with the man layout</title>
<section>
<title>Browsing the man layout</title>
<body>

<p>
Now that we understand the man layout, we can begin to look it over for
commands. Sometimes we may need to narrow down what man page we want. The first
way would be addressing by section. To found out a description of a section,
once can use  <c>man section intro</c> like so:
</p>

<pre caption="Using man intro to describe a section">
$ man 3 intro
<comment>(Output slightly modified to fit the document properly)</comment>
INTRO(3)               Linux Programmer's Manual                INTRO(3)



NAME
       intro - Introduction to library functions

DESCRIPTION
       This chapter describes all library functions excluding the library
       functions described in chapter 2, which implement system calls.
       There are various function groups which can be identified by a
       letter which is appended to the chapter number:
....
</pre>

<p>
Unfortunately, this doesn't always work! However, luckily for us there is
another way to search for commands that may return multiple results (such as a
library call and system command having the same name). To do so, we use the
<c>-K</c> parameter to man like so:
</p>

<pre caption="Using man -K to search by string">
$ <i>man -K sleep</i>
/usr/share/man/man0p/time.h.0p.gz? [ynq] <i>n</i>
/usr/share/man/man0p/unistd.h.0p.gz? [ynq] <i>n</i>
/usr/share/man/man2/alarm.2.gz? [ynq] <i>n</i>
/usr/share/man/man2/pause.2.gz? [ynq] <i>n</i>
/usr/share/man/man2/futex.2.gz? [ynq] <i>n</i>
/usr/share/man/man2/nanosleep.2.gz? [ynq] <i>y</i>
/usr/share/man/man2/semop.2.gz? [ynq] <i>q</i>
</pre>

<p>
Sometimes the output may be a lot larger. In this case it might be better to
specify more specific keywords. Now that we know where to find the man page,
the next section will look at viewing the man page.
</p>

</body>
</section>
<section>
<title>Viewing man pages</title>
<body>

<p>
Viewing man pages can be done in 2 ways, first is with <c>man [man page
name]</c>. The second way is <c>man [section] [man page name]</c>. Let's take
<c>bc</c> for example. I can view either the first man page that comes up on
<c>bc</c> (which would be section 1, because it is the lowest section
containing a man page on <c>bc</c>):
</p>

<pre caption="Viewing the default man page">
$ <i>man bc</i>
bc(1)                                            bc(1)


NAME
       bc - An arbitrary precision calculator language
...
</pre>

<p>
However, what if I want the POSIX version? Then I can use the second form:
</p>

<pre caption="Viewing a specific man page by section">
$ <i>man 1p bc</i>
BC(P)        POSIX Programmer's Manual           BC(P)


NAME
       bc - arbitrary-precision arithmetic language
...
</pre>

<p>
And the man page is displayed. Now that we have the man page up, it's time to
work with it. The next section will look at navigation and searching.
</p>

</body>
</section>
<section>
<title>Navigating and searching man pages</title>
<body>

<p>
Navigating a man page is fairly simple. To move up and down line by line, use
the up and down arrow keys. To move up page by page, you can use the page up
and page down keys. Do however note that these navigation instructions assume
the environmental <c>PAGER</c> variable is set to use the default pager,
<c>less</c>. Less also has a few other commands for navigation, but the arrow
keys usually suffice:
</p>

<pre caption="Additional less navigation keys">
  e  ^E  j  ^N  CR  *  Forward  one line   (or N lines).
  y  ^Y  k  ^K  ^P  *  Backward one line   (or N lines).
  f  ^F  ^V  SPACE  *  Forward  one window (or N lines).
  b  ^B  ESC-v      *  Backward one window (or N lines).
  z                 *  Forward  one window (and set window to N).
  w                 *  Backward one window (and set window to N).
  ESC-SPACE         *  Forward  one window, but don't stop at end-of-file.
  d  ^D             *  Forward  one half-window (and set half-window to N).
  u  ^U             *  Backward one half-window (and set half-window to N).
  ESC-)  RightArrow *  Left  one half screen width (or N positions).
  ESC-(  LeftArrow  *  Right one half screen width (or N positions).
  F                    Forward forever; like "tail -f".
</pre>

<p>
Searching, however, is more intesting. The two most basic searches are
<c>/pattern</c> and <c>?pattern</c>. The first version searches forwards, and
the second searches backwards. <c>pattern</c> is a regular expression pattern
that is described in <c>man 7 regex</c>. Let's take for example searching for
the <c>-D</c> option to <c>emerge</c>. First, bring up the emerge man page:
</p>

<pre caption="Bringing up the emerge man page">
$ <i>man emerge</i>
</pre>

<p>
Then, at the screen, press the <c>/</c> key to bring up the entry prompt to
search forwards and enter in our search pattern:
</p>

<pre caption="Bringing up the forward search prompt">
     gracefully handles updating installed packages to newer releases as well.
     It handles both source and binary packages, and it can be used to create
     binary packages for distribution.

EBUILDS, TBZ2S, CLASSES AND DEPENDENCIES
/<i>\-D</i>
</pre>

<note>
The <c>\</c> is done to escape the <c>-</c> sign, which would normally be used
as part of a regular expression.
</note>

<p>
This will search the man page, and bring the searched item into focus:
</p>

<pre caption="Forward search results">
  --deep (-D)
        When used in conjunction with --update, this flag forces emerge to consider the entire
        dependency tree of packages, instead of checking only the immediate dependencies of
        the packages.  As an example, this catches updates in libraries that are not directly
        listed in the  dependencies of a package.
</pre>

<p>
If you hit a search result by accident and want to continue searching for the
same results, simply press the <c>/</c> key again, and press enter (ie. don't
put a pattern it). This will cause the search to default to the last pattern
used. Now with some man pages, options are listed, then explained later on.
Take the <c>man 5 portage</c> man page. It lists the files used, then explains
their usage. Searching forward a few times would return the results, but
there's an easier way to handle this, with the second search form, backwards
searching. Let's use this to find the description on
<path>package.unmask</path>. First, bring up <c>man 5 portage</c>:
</p>

<pre caption="Bringing up the man 5 portage man page">
$ <i>man 5 portage</i>
</pre>

<p>
Now press <c>SHIFT+g</c>. This will bring you to the end of the page:
</p>

<pre caption="End of the man page after SHIFT+g">
SEE ALSO
       emerge(1), ebuild(1), ebuild(5), make.conf(5)

Portage 2.0.51        Jan 2004            PORTAGE(5)
lines 418-442/442 (END)
</pre>

<p>
Now we'll go ahead and enter the pattern to search for with the <c>?pattern</c>
backwards search option. First press the <c>?</c> key to bring up the prompt,
and then enter in <c>package.unmask</c>, our query:
</p>

<pre caption="Specifying our search">
SEE ALSO
       emerge(1), ebuild(1), ebuild(5), make.conf(5)

Portage 2.0.51        Jan 2004           PORTAGE(5)
?<i>package.unmask</i>
</pre>

<p>
Then hit enter to bring up the result:
</p>

<pre caption="Our search result">
  package.unmask
       Just like package.mask above, except here you list packages you want to unmask.
       Useful for overriding the global  package.mask  file (see below).  Note that
       this does not override packages that are masked via KEYWORDS.
...
</pre>

<p>
And the search is complete! Note that just as with <c>/</c>, using <c>?</c>
search with no pattern will use the last pattern to search.
</p>

</body>
</section>
<section>
<title>Conclusion</title>
<body>

<p>
This concludes the man guide. This will hopefully shed some light on navigating
man pages, and maybe even give a few new tips to the more experienced users.
For those who prefer alternate means of navigating man pages, the following are
also avaliable:
</p>

<ul>
  <li>app-text/man2html - a program for converting man pages to html</li>
  <li>app-text/tkman - a tk based man page browser</li>
</ul>

<p>
Also the <c>KDE</c> web browser <c>Konqueror</c> can browse man pages using the
<c>man:</c> syntax in the address bar.
</p>

</body>
</section>
</chapter>
</guide>



-- 
gentoo-doc-cvs@g.o mailing list