Difference between revisions of "Man page/Navigate"

From Gentoo Wiki
Jump to: navigation, search
(Marked this version for translation)
m (added some Package templates)
 
(6 intermediate revisions by one user not shown)
Line 13: Line 13:
  
 
<!--T:4-->
 
<!--T:4-->
Everyone at some point in their linux life has used it. "It" is the <code>man</code> 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 help shed some light on these capabilities.  
+
Everyone at some point in their Linux life has used it. "It" is the <code>man</code> 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 help shed some light on these capabilities.
  
 
=== Man layout === <!--T:5-->
 
=== Man layout === <!--T:5-->
  
 
<!--T:6-->
 
<!--T:6-->
Man pages are mainly stored in the {{Path|/usr/share/man}} directory. However, as long as a man page is located in the <code>MANPATH</code> environment variable, man will be able to pick it up. Gentoo will generally store <code>MANPATH</code> variables in {{Path|/etc/env.d}} . 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:  
+
Man pages are mainly stored in the {{Path|/usr/share/man}} directory. However, as long as a man page is located in the <code>MANPATH</code> environment variable, man will be able to pick it up. Gentoo will generally store <code>MANPATH</code> variables in {{Path|/etc/env.d}}. 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:  
  
 
<!--T:7-->
 
<!--T:7-->
Line 60: Line 60:
 
|-  
 
|-  
 
| man3
 
| man3
| This section describes standard c library functions.
+
| This section describes standard C library functions.
 
|-  
 
|-  
 
| man4
 
| man4
Line 81: Line 81:
 
|-  
 
|-  
 
| mann
 
| mann
| This section is mainly used by <code>Tcl/Tk</code> . The <code>n</code> stands for new.
+
| This section is mainly used by <code>Tcl/Tk</code>. The <code>n</code> stands for new.
 
|-
 
|-
 
|}
 
|}
  
 
<!--T:10-->
 
<!--T:10-->
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.  
+
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.
  
 
== Working with the man layout == <!--T:11-->
 
== Working with the man layout == <!--T:11-->
Line 135: Line 135:
  
 
<!--T:19-->
 
<!--T:19-->
Viewing man pages can be done in 2 ways, first is with <code>man [man page name]</code> . The second way is <code>man [section] [man page name]</code> . Let's take <code>bc</code> for example. I can view either the first man page that comes up on <code>bc</code> (which would be section 1, because it is the lowest section containing a man page on <code>bc</code> ):  
+
Viewing man pages can be done in 2 ways, first is with <code>man [man page name]</code> . The second way is <code>man [section] [man page name]</code>. Let's take <code>bc</code> for example. I can view either the first man page that comes up on <code>bc</code> (which would be section 1, because it is the lowest section containing a man page on <code>bc</code>):  
  
 
<!--T:20-->
 
<!--T:20-->
Line 163: Line 163:
  
 
<!--T:23-->
 
<!--T:23-->
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.  
+
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.
  
 
=== Navigating and searching man pages === <!--T:24-->
 
=== Navigating and searching man pages === <!--T:24-->
  
 
<!--T:25-->
 
<!--T:25-->
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 <code>PAGER</code> variable is set to use the default pager, <code>less</code> . Less also has a few other commands for navigation, but the arrow keys usually suffice:  
+
Navigating a man page is fairly simple. To move up and down line by line, use the {{Key|Up}} and {{Key|Down}} arrow keys. To move up page by page, you can use the {{Key|Page up}} and {{Key|Page down}} keys. Do however note that these navigation instructions assume the environmental <code>PAGER</code> variable is set to use the default pager, <code>less</code>. Less also has a few other commands for navigation, but the arrow keys usually suffice:  
  
 
<!--T:26-->
 
<!--T:26-->
Line 188: Line 188:
  
 
<!--T:27-->
 
<!--T:27-->
Searching, however, is more interesting. The two most basic searches are <code>/pattern</code> and <code>?pattern</code> . The first version searches forwards, and the second searches backwards. <code>pattern</code> is a regular expression pattern that is described in <code>man 7 regex</code> . Let's take for example searching for the <code>-D</code> option to <code>emerge</code> . First, bring up the emerge man page:  
+
Searching, however, is more interesting. The two most basic searches are <code>/pattern</code> and <code>?pattern</code>. The first version searches forwards, and the second searches backwards. <code>pattern</code> is a regular expression pattern that is described in <code>man 7 regex</code>. Let's take for example searching for the <code>-D</code> option to <code>emerge</code>. First, bring up the emerge man page:  
  
 
<!--T:28-->
 
<!--T:28-->
Line 194: Line 194:
  
 
<!--T:29-->
 
<!--T:29-->
Then, at the screen, press the <code>/</code> key to bring up the entry prompt to search forwards and enter in our search pattern:  
+
Then, at the screen, press the {{Key|/}} key to bring up the entry prompt to search forwards and enter in our search pattern:  
  
 
<!--T:30-->
 
<!--T:30-->
Line 224: Line 224:
  
 
<!--T:34-->
 
<!--T:34-->
If you hit a search result by accident and want to continue searching for the same results, simply press the <code>/</code> key again, and press enter (i.e. 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 <code>man 5 portage</code> 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}} . First, bring up <code>man 5 portage</code> :  
+
If you hit a search result by accident and want to continue searching for the same results, simply press the {{Key|/}} key again, and press {{Key|Enter}} (i.e. 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 <code>man 5 portage</code> 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}}. First, bring up <code>man 5 portage</code>:  
  
 
<!--T:35-->
 
<!--T:35-->
Line 230: Line 230:
  
 
<!--T:36-->
 
<!--T:36-->
Now press <code>SHIFT+g</code> . This will bring you to the end of the page:  
+
Now press {{Key|Shift}} + {{Key|g}}. This will bring you to the end of the page:  
  
 
<!--T:37-->
 
<!--T:37-->
Line 243: Line 243:
  
 
<!--T:38-->
 
<!--T:38-->
Now we'll go ahead and enter the pattern to search for with the <code>?pattern</code> backwards search option. First press the <code>?</code> key to bring up the prompt, and then enter in <code>package.unmask</code> , our query:  
+
Now we'll go ahead and enter the pattern to search for with the <code>?pattern</code> backwards search option. First press the {{Key|?}} key to bring up the prompt, and then enter in <code>package.unmask</code>, our query:  
  
 
<!--T:39-->
 
<!--T:39-->
Line 256: Line 256:
  
 
<!--T:40-->
 
<!--T:40-->
Then hit enter to bring up the result:  
+
Then hit {{Key|Enter}} to bring up the result:  
  
 
<!--T:41-->
 
<!--T:41-->
Line 269: Line 269:
  
 
<!--T:42-->
 
<!--T:42-->
And the search is complete! Note that just as with <code>/</code> , using <code>?</code> search with no pattern will use the last pattern to search.
+
And the search is complete! Note that just as with <code>/</code>, using <code>?</code> search with no pattern will use the last pattern to search.
  
 
=== Conclusion === <!--T:43-->
 
=== Conclusion === <!--T:43-->
Line 277: Line 277:
  
 
<!--T:45-->
 
<!--T:45-->
* app-text/man2html - a program for converting man pages to html
+
* {{Package|app-text/man2html}} - a program for converting man pages to html
* app-text/tkman - a tk based man page browser
+
* {{Package|app-text/tkman}} - a tk based man page browser
  
 
<!--T:46-->
 
<!--T:46-->
Also the <code>KDE</code> web browser <code>Konqueror</code> can browse man pages using the <code>man:</code> syntax in the address bar.  
+
Also the <code>KDE</code> web browser <code>Konqueror</code> can browse man pages using the <code>man:</code> syntax in the address bar.
  
 
== Acknowledgements == <!--T:47-->
 
== Acknowledgements == <!--T:47-->

Latest revision as of 17:09, 28 February 2014

Other languages:English 100% • ‎français 100% • ‎한국어 100% • ‎русский 100%

This guide shows how to navigate man pages using man.

Introduction

The man program

Everyone at some point in their Linux life has used it. "It" is the man 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 help shed some light on these capabilities.

Man layout

Man pages are mainly stored in the /usr/share/man directory. However, as long as a man page is located in the MANPATH environment variable, man will be able to pick it up. Gentoo will generally store MANPATH variables in /etc/env.d. 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:

user $ ls /usr/share/man | grep man
man0p
man1
man1p
man2
man3
man3p
man4
man5
man6
man7
man8
man9
mann

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

Man Directory Description
man0p The p 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.
man1 This section is for standard commands. Most programs will put their man pages here, so this section tends to be the largest.
man1p This section describes the POSIX versions of the commands described in 1p. Since it only describes basic commands, it is much smaller than man1.
man2 This section describes Linux kernel system calls.
man3 This section describes standard C library functions.
man4 This section describes special devices. These devices are generally kernel oriented, but Xorg-X11 has entries in here as well.
man5 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 man 5 portage for a description of the portage file structure, and man 5 make.conf for make.conf makeup.
man6 This section introduces games and other special toys.
man7 This section describes standards and other miscellaneous items. These standards can include things such as charsets, SQL statements, ISO standards and regular expressions.
man8 This section describes administrative commands (those usually run by the root user).
man9 This section is somewhat sparse, but is meant to contain documentation for various parts of the kernel.
mann This section is mainly used by Tcl/Tk. The n stands for new.

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.

Working with the man layout

Browsing the man layout

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 man section intro like so:

user $ man 3 intro
## (Output slightly modified to fit the document properly)
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:
....

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 -K parameter to man like so:

user $ man -K sleep
/usr/share/man/man0p/time.h.0p.gz? [ynq] n
/usr/share/man/man0p/unistd.h.0p.gz? [ynq] n
/usr/share/man/man2/alarm.2.gz? [ynq] n
/usr/share/man/man2/pause.2.gz? [ynq] n
/usr/share/man/man2/futex.2.gz? [ynq] n
/usr/share/man/man2/nanosleep.2.gz? [ynq] y
/usr/share/man/man2/semop.2.gz? [ynq] q

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.

Viewing man pages

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

user $ man bc
bc(1)                                            bc(1)
 
 
NAME
       bc - An arbitrary precision calculator language
...

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

user $ man 1p bc
BC(P)        POSIX Programmer's Manual           BC(P)
 
 
NAME
       bc - arbitrary-precision arithmetic language
...

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.

Navigating and searching man pages

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 PAGER variable is set to use the default pager, less. Less also has a few other commands for navigation, but the arrow keys usually suffice:

CodeAdditional 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 *  Shift view right  one half screen width (or N positions).
  ESC-(  LeftArrow  *  Shift view left one half screen width (or N positions).
  F                    Forward forever; like "tail -f".

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

user $ man emerge

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

CodeBringing 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
/\-D
Note
The \ is done to escape the - sign, which would normally be used as part of a regular expression.

This will search the man page, and bring the searched item into focus:

CodeForward 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.

If you hit a search result by accident and want to continue searching for the same results, simply press the / key again, and press Enter (i.e. 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 man 5 portage 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 package.unmask. First, bring up man 5 portage:

user $ man 5 portage

Now press Shift + g. This will bring you to the end of the page:

CodeEnd 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)

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

CodeSpecifying our search

SEE ALSO
       emerge(1), ebuild(1), ebuild(5), make.conf(5)
 
Portage 2.0.51        Jan 2004           PORTAGE(5)
?package.unmask

Then hit Enter to bring up the result:

CodeOur 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.
...

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

Conclusion

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 available:

Also the KDE web browser Konqueror can browse man pages using the man: syntax in the address bar.

Acknowledgements

We would like to thank the following authors and editors for their contributions to this guide:

  • Chris White