[2024-feb-29] Sad news: Eric Layton aka Nocturnal Slacker aka vtel57 passed away on Feb 26th, shortly after hospitalization. He was one of our Wiki's most prominent admins. He will be missed.

Welcome to the Slackware Documentation Project

This is an old revision of the document!


How to search and read Manpages efficiently

I hope this Howto can help some of you, 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:

markus@samsung:~$ 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

With the whatis command:

markus@samsung:~$ whatis dhcp                                                     
dhcp []              (5)  - eval - ISC DHCP conditional evaluation                
dhcp []              (5)  - options - Dynamic Host Configuration Protocol options 

For both commands, the search is case-insensitive!

Updating the ''whatis'' Database

The whatiscommand 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 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.

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      System File Formats and Conventions 
       6      Games, etc. 
       7      Miscellaneous pages 
       8      System Administration tools and Daemons

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

markus@samsung:~$ 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 

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:

man 7 man

The Structure of the Manpages

The manpages have (should have) all 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. With / one searches the document forward, with ? backwards. With n the cursor jumps to the next match. The - 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

 -h, --human-readable 
              with -l, print sizes in human readable format (e.g., 1K 234M 2G)

Navigation is like in vi:

  • G end of the manpage
  • gg first line of the mapage
  • nG nth line of the manpage

One can also set marks at a line of the manpage

  • ma sets mark a in the current line
  • 'a jumps to mark a in the manpage

Unfortunately these marks are lost when you leave the manpage (which is done with q).

Formatting a Manpage as a PDF-document

If you want to have a manpage as a PDF document you can use the command:

man -t ls | ps2pdf - > ls-manpage.pdf

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 read the manpages listed in “see also”.

Sources

 howtos:general_admin:searching_and_reading_manpages_efficiently ()