howtos:general_admin:searching_and_reading_manpages_efficiently

The Wiki has moved to new hardware, and the old server died.
Welcome to the Slackware Documentation Project
You are here: start » howtos » general_admin » searching_and_reading_manpages_efficiently
This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
<!-- Reviewed 2013-01-06 mfillpot -->
<!-- Reviewed 2012-12-31 hazel -->
<!-- Add your text below. We strongly advise to start with a Headline (see button bar above). -->
====== How to search and read Manpages efficiently ======

Manpages are pages in the online Unix Manual. I hope this Howto can help
some of you to use them more effectively, although I'm aware that many of
the readers are already familiar with this subject.

===== Searching for a Manpage =====
In order to search for information about anything in the manpages you can
use one of the following commands:
  * ''apropos''
  * ''man -k''
  * ''whatis''
''apropos'' is only an alias for ''man -k''; there is no difference between
them. The difference between ''whatis'' and the other commands is that
''whatis'' searches for whole words whereas ''apropos'' (or ''man -k''
respectively) searches for parts of strings.

If you don't know how exactly a word, for example a command, is written, you
can use ''apropos''. If you know exactly the word to search for, ''whatis''
would be more efficient because it results in fewer lines of output.

=== Example ===
Searching for information about DHCP:

With the ''apropos'' command:
<code>
user@darkstar$ apropos dhcp
dhclient []          (8)  - script - DHCP client network configuration script
dhclient.conf []     (5)  - DHCP client configuration file
dhclient.leases []   (5)  - DHCP client lease database
dhcp []              (5)  - eval - ISC DHCP conditional evaluation
dhcp []              (5)  - options - Dynamic Host Configuration Protocol options
dhcpcd []            (8)  - an RFC 2131 compliant DHCP client
dhcpcd []            (8)  - run-hooks - DHCP client configuration script
dhcpcd.conf []       (5)  - dhcpcd configuration file
dhcpctl_initialize [] (3)  - dhcpctl library initialization
dhcpctl_initialize [] (3p)  - dhcpctl library initialization
dhcpd []             (8)  - Dynamic Host Configuration Protocol Server
dhcpd.conf []        (5)  - dhcpd configuration file
dhcpd.leases []      (5)  - DHCP client lease database
dnsmasq []           (8)  - A lightweight DHCP and caching DNS server
</code>
With the ''whatis'' command:
<code>
user@darkstar$ whatis dhcp
dhcp []              (5)  - eval - ISC DHCP conditional evaluation
dhcp []              (5)  - options - Dynamic Host Configuration Protocol options
</code>
For both commands, the search is case-insensitive!

===== Updating the ''whatis'' Database =====
The ''whatis''command has its own database. The manpages for any packages of
the stock Slackware installation are already present in the database. This
is also true if you upgrade such packages. But if you build your own
packages from source, for example from
[[http://www.slackbuilds.org|SlackBuilds.org]], the manpages for these
packages are not yet present in the ''whatis'' database. In order to update
the database after installing new packages, Slackware provides the
''makewhatis'' command. It has to be executed as root.

Please note that some other distributions use the ''mandb'' command for this
purpose.

===== Sections in the Manual =====
Don't confuse these sections with the sections within the structure of each
manpage; they are described in the paragraph below.

The manpages manual is divided into eight different sections. Here is an
extract from the manpage for the ''man'' command.
<code>
MANUAL SECTIONS 
       The standard sections of the manual include: 
       1      User Commands 
       2      System Calls 
       3      C Library Functions 
       4      Devices and Special Files 
       5      File Formats and Conventions 
       6      Games et. Al. 
       7      Miscellanea
       8      System Administration tools and Daemons
</code>
If the manual pages for a topic are divided over different sections, one can
pass the section number as an additional argument to the ''man'' command.
=== Example ===
<code>
user@darkstar$ apropos man  
 ... 
makecontext []       (3)  - manipulate user context 
makedev []           (3)  - manage a device number 
man []               (1)  - format and display the on-line manual pages 
man []               (7)  - macros to format man pages 
man []               (7)  - pages - conventions for writing Linux man pages 
man.conf []          (5)  - configuration data for man 
man2html []          (1)  - format a manual page in html 
manuals with []      (7)  - mdoc 
</code>
Now if you want to read the manpage about "macros to format man pages" in
section 7 you'll have to execute the following command:
<code>
user@darkstar$ man 7 man
</code>

===== The Structure of the Manpages =====
The manpages all have (or should have) the same structure:
  * Name
    * Name of the command and a short description of its function(s)
  * Synopsis
    * A usage statement including a short list of the options
  * Description
    * A detailed explanation of the command
  * Options
    * Detailed explanation of the command line options for the command
  * Bugs
    * Known Bugs
  * Author
    * The author(s) of the package and maybe the author of the manpage
  * See also
    * Advice for manpages about similar or related programs

If one searches for information about a subject rather than a single
 command the "see also" line is very interesting.

===== Searching within a Manpage =====
The reader for the manpages is the program ''less''. Its keybindings are
very similar to the vi editor.

  * <key>'/'</key> searches the document forward
  * <key>'?'</key> searched the document backwards
  * <key>'n'</key> the cursor jumps to the next match.

The <key>Minus</key> key has no special meaning in the search patterns, so it is
possible to search (for example) for the -k option with ///-k//

===Example===
Searching for the //-h// option in the manpage for the ''ls'' command with
 //-h// gives us
<code>
 -h, --human-readable 
              with -l, print sizes in human readable format (e.g., 1K 234M 2G)
</code>

===== Navigation within a Manpage =====
Navigation commands are like those in vi:
  * <key>'G'</key> end of the manpage
  * <key>g</key>,<key>g</key> first line of the manpage
  * //n//,<key>'G'</key> nth line of the manpage

One can also **set marks** at a line of the manpage
  * //<key>m</key>,a// sets mark a in the current line
  * //<key>'</key>, a// jumps to mark a in the manpage
Unfortunately these marks are lost when you leave the manpage (which is
done with <key>q</key>).

===== Formatting a Manpage as a PDF-document =====
If you want to have a manpage as a PDF document you can use the command:
<code>man -t ls | ps2pdf - > ls-manpage.pdf</code>
which formats the manpage for the ''ls'' command into a pdf document
named "ls-manpage.pdf".

===== Further Reading =====
For more information read the manpage for the ''man'' command and the
manpages listed in "see also".
====== Sources ======
<!-- If you are copying information from another source, then specify that source -->
<!-- * Original source: [[http://some.website.org/some/page.html]] -->
<!-- Authors are allowed to give credit to themselves! -->
  * Originally written by [[wiki:user:markush|Markus Hutmacher]] 
<!-- * Contributions by [[wiki:user:markush]] -->

<!-- Please do not modify anything below, except adding new tags.-->
<!-- You must remove the tag-word "template" below before saving your new page -->
{{tag>howtos manpages searching documentation information author_markush }}
Trace:
Navigation

Search

Toolbox

In Other Languages

SlackDocs

Slackware Links

QR Code
