Difference between revisions of "Man page"

From ArchWiki
Jump to: navigation, search
(Colored man pages on xterm/rxvt-unicode: added Note about usage of ~/.Xdefaults and ~/.Xresources; added Package Official formatting; misc. formatting changes)
m (codeline -> ic)
Line 10: Line 10:
 
{{Article summary end}}
 
{{Article summary end}}
  
'''Man pages''' (abbreviation for "manual pages") are the extensive documentation that comes preinstalled with almost all substantial UNIX-like operating systems, including Arch Linux. The command used to display them is {{Codeline|man}}.
+
'''Man pages''' (abbreviation for "manual pages") are the extensive documentation that comes preinstalled with almost all substantial UNIX-like operating systems, including Arch Linux. The command used to display them is {{Ic|man}}.
  
 
In spite of their scope, man pages are designed to be self-contained documents, consequentially limiting themselves to referring to other man pages when discussing related subjects. This is in sharp contrast with the hyperlink-aware info files, GNU's attempt at replacing the traditional man page format.
 
In spite of their scope, man pages are designed to be self-contained documents, consequentially limiting themselves to referring to other man pages when discussing related subjects. This is in sharp contrast with the hyperlink-aware info files, GNU's attempt at replacing the traditional man page format.
Line 33: Line 33:
 
  $ man 5 passwd
 
  $ man 5 passwd
  
to read the man page on {{Codeline|/etc/passwd}}, rather than the {{Codeline|passwd}} utility.
+
to read the man page on {{Ic|/etc/passwd}}, rather than the {{Ic|passwd}} utility.
  
Very brief descriptions of programs can be read out of man pages without displaying the whole page using the {{Codeline|whatis}} command. For example, for a brief description of ls, type:
+
Very brief descriptions of programs can be read out of man pages without displaying the whole page using the {{Ic|whatis}} command. For example, for a brief description of ls, type:
  
 
  $ whatis ls
 
  $ whatis ls
  
and {{Codeline|whatis}} will output "list directory contents."
+
and {{Ic|whatis}} will output "list directory contents."
  
 
==Format==
 
==Format==
Line 55: Line 55:
  
 
==Searching manuals==
 
==Searching manuals==
Whilst the {{Codeline|man}} utility allows users to display man pages, a problem arises when one knows not the exact name of the desired manual page in the first place! Fortunately, the {{Codeline|-k}} or {{Codeline|--apropos}} options can be used to search the manual page descriptions for instances of a given keyword. For example, to search for man pages related to "password":
+
Whilst the {{Ic|man}} utility allows users to display man pages, a problem arises when one knows not the exact name of the desired manual page in the first place! Fortunately, the {{Ic|-k}} or {{Ic|--apropos}} options can be used to search the manual page descriptions for instances of a given keyword. For example, to search for man pages related to "password":
  
 
  $ man -k password
 
  $ man -k password
Line 63: Line 63:
 
  $ man --apropos password
 
  $ man --apropos password
  
This is equivalent to calling the {{Codeline|apropos}} command:
+
This is equivalent to calling the {{Ic|apropos}} command:
  
 
  $ apropos password
 
  $ apropos password
Line 72: Line 72:
 
For some users, color-enabled man pages allow for a clearer presentation and easier digestion of the content. Given that users new to Linux are prone to spend a considerable amount of time familiarizing themselves with basic userspace tools, setting up a comfortable environment is a necessity to most.
 
For some users, color-enabled man pages allow for a clearer presentation and easier digestion of the content. Given that users new to Linux are prone to spend a considerable amount of time familiarizing themselves with basic userspace tools, setting up a comfortable environment is a necessity to most.
  
There are two prevalent methods for achieving colored man pages: using {{Codeline|most}}, or opting for {{Codeline|less}}. The former is simpler to configure, at the expense of the advanced functionality that is native to {{Codeline|less}}.
+
There are two prevalent methods for achieving colored man pages: using {{Ic|most}}, or opting for {{Ic|less}}. The former is simpler to configure, at the expense of the advanced functionality that is native to {{Ic|less}}.
  
 
===First method: using 'most'===
 
===First method: using 'most'===
 
Install {{package Official|most}} using [[pacman]]:
 
Install {{package Official|most}} using [[pacman]]:
 
  # pacman -S most
 
  # pacman -S most
This is similar to {{Codeline|less}} and {{Codeline|more}}, yet allows rendering colored text in an easier way.
+
This is similar to {{Ic|less}} and {{Ic|more}}, yet allows rendering colored text in an easier way.
  
 
Edit {{Filename|/etc/man_db.conf}}, uncomment the pager definition and change it to:
 
Edit {{Filename|/etc/man_db.conf}}, uncomment the pager definition and change it to:
Line 90: Line 90:
 
  color underline yellow black
 
  color underline yellow black
 
  color overstrike brightblue black
 
  color overstrike brightblue black
Another example showing keybindings similar to {{Codeline|less}} (jump to line is set to 'J'):
+
Another example showing keybindings similar to {{Ic|less}} (jump to line is set to 'J'):
 
  % less-like keybindings
 
  % less-like keybindings
 
  unsetkey "^K"
 
  unsetkey "^K"
Line 131: Line 131:
 
:<small>''Source: [http://nion.modprobe.de/blog/archives/572-less-colors-for-man-pages.html nion's blog - less colors for man pages]''</small>
 
:<small>''Source: [http://nion.modprobe.de/blog/archives/572-less-colors-for-man-pages.html nion's blog - less colors for man pages]''</small>
  
Alternatively, getting an approximate coloured result in manual pages with {{Codeline|less}} is also a possibility. This method has the advantage that {{Codeline|less}} has a bigger feature set than {{Codeline|most}}, and that might be the preference for advanced users.
+
Alternatively, getting an approximate coloured result in manual pages with {{Ic|less}} is also a possibility. This method has the advantage that {{Ic|less}} has a bigger feature set than {{Ic|most}}, and that might be the preference for advanced users.
  
 
Add the following to a shell configuration file. For [[Bash]] it would be {{Filename|~/.bashrc}}:
 
Add the following to a shell configuration file. For [[Bash]] it would be {{Filename|~/.bashrc}}:
Line 154: Line 154:
 
:<small>''Source:[http://pub.ligatura.org/fs/xfree86/xresources/xterm XFree resources file for XTerm program]''</small>
 
:<small>''Source:[http://pub.ligatura.org/fs/xfree86/xresources/xterm XFree resources file for XTerm program]''</small>
  
A quick way to add color to manual pages viewed on {{Package Official|xterm}}/{{Codeline|uxterm}} or {{Package Official|rxvt-unicode}} can be made modifying the {{Filename|~/.Xdefaults}} file.
+
A quick way to add color to manual pages viewed on {{Package Official|xterm}}/{{Ic|uxterm}} or {{Package Official|rxvt-unicode}} can be made modifying the {{Filename|~/.Xdefaults}} file.
  
 
{{Note|If {{Filename|~/.Xdefaults}} does not work for you, you can try using {{Filename|~/.Xresources}}.}}
 
{{Note|If {{Filename|~/.Xdefaults}} does not work for you, you can try using {{Filename|~/.Xresources}}.}}
Line 174: Line 174:
 
  $ xrdb -load ~/.Xresources
 
  $ xrdb -load ~/.Xresources
  
Launch a new {{Codeline|xterm/uxterm}} or {{Codeline|rxvt-unicode}} and you should see colorful man pages.
+
Launch a new {{Ic|xterm/uxterm}} or {{Ic|rxvt-unicode}} and you should see colorful man pages.
This combination puts colors to '''bold''' and <u>underlined</u> words in {{Codeline|xterm/uxterm}} or to '''bold''', <u>underlined</u>, and ''italicized'' text in {{Codeline|rxvt-unicode}}. You can play with different combinations of this attributes (see the [http://pub.ligatura.org/fs/xfree86/xresources/xterm sources] of this item).
+
This combination puts colors to '''bold''' and <u>underlined</u> words in {{Ic|xterm/uxterm}} or to '''bold''', <u>underlined</u>, and ''italicized'' text in {{Ic|rxvt-unicode}}. You can play with different combinations of this attributes (see the [http://pub.ligatura.org/fs/xfree86/xresources/xterm sources] of this item).
  
 
==Reading man pages with a browser==
 
==Reading man pages with a browser==
Line 188: Line 188:
 
  $ man free | man2html -compress -cgiurl man$section/$title.$section$subsection.html > ~/man/free.html
 
  $ man free | man2html -compress -cgiurl man$section/$title.$section$subsection.html > ~/man/free.html
  
Another use for {{codeline|man2html}} is exporting to raw, printer-friendly text:
+
Another use for {{Ic|man2html}} is exporting to raw, printer-friendly text:
 
  $ man free | man2html -bare > ~/free.txt
 
  $ man free | man2html -bare > ~/free.txt
  

Revision as of 17:31, 11 December 2011

This template has only maintenance purposes. For linking to local translations please use interlanguage links, see Help:i18n#Interlanguage links.


Local languages: Català – Dansk – English – Español – Esperanto – Hrvatski – Indonesia – Italiano – Lietuviškai – Magyar – Nederlands – Norsk Bokmål – Polski – Português – Slovenský – Česky – Ελληνικά – Български – Русский – Српски – Українська – עברית – العربية – ไทย – 日本語 – 正體中文 – 简体中文 – 한국어


External languages (all articles in these languages should be moved to the external wiki): Deutsch – Français – Română – Suomi – Svenska – Tiếng Việt – Türkçe – فارسی

Summary help replacing me
Information on man pages, along with recommendations on how to improve their usage

Man pages (abbreviation for "manual pages") are the extensive documentation that comes preinstalled with almost all substantial UNIX-like operating systems, including Arch Linux. The command used to display them is man.

In spite of their scope, man pages are designed to be self-contained documents, consequentially limiting themselves to referring to other man pages when discussing related subjects. This is in sharp contrast with the hyperlink-aware info files, GNU's attempt at replacing the traditional man page format.

Accessing Man Pages

To read a man page, simply enter:

$ man page_name

Manuals are sorted into several sections:

  1. General commands
  2. System calls (functions provided by the kernel)
  3. Library calls (C library functions)
  4. Special files (usually found in /dev) and drivers
  5. File formats and conventions
  6. Games
  7. Miscellaneous (including conventions)
  8. System administration commands (usually requiring root privileges) and daemons

Man pages are usually referred to by their name, followed by their section number in parentheses. Often there are multiple man pages of the same name, such as man(1) and man(7). In this case, give man the section number followed by the name of the man page, for example:

$ man 5 passwd

to read the man page on /etc/passwd, rather than the passwd utility.

Very brief descriptions of programs can be read out of man pages without displaying the whole page using the whatis command. For example, for a brief description of ls, type:

$ whatis ls

and whatis will output "list directory contents."

Format

Man pages all follow a fairly standard format, which helps in navigating them. Some sections which are often present include:

  • NAME - The name of the command and a one-line statement of its purpose.
  • SYNOPSIS - A list of the options and arguments a command takes or the parameters the function takes and its header file.
  • DESCRIPTION - A more in depth description of a command or function's purpose and workings.
  • EXAMPLES - Common examples, usually ranging from the simple to the relatively complex.
  • OPTIONS - Descriptions of each of the options a command takes and what they do.
  • EXIT STATUS - The meanings of different exit codes.
  • FILES - Files related to a command or function.
  • BUGS - Problems with the command or function that are pending repair. Also known as KNOWN BUGS.
  • SEE ALSO - A list of related commands or functions.
  • AUTHOR, HISTORY, COPYRIGHT, LICENSE, WARRANTY - Information about the program, its past, its terms of use, and its creator.

Searching manuals

Whilst the man utility allows users to display man pages, a problem arises when one knows not the exact name of the desired manual page in the first place! Fortunately, the -k or --apropos options can be used to search the manual page descriptions for instances of a given keyword. For example, to search for man pages related to "password":

$ man -k password

or:

$ man --apropos password

This is equivalent to calling the apropos command:

$ apropos password

The given keyword is interpreted as a regular expression by default.

Colored man pages

For some users, color-enabled man pages allow for a clearer presentation and easier digestion of the content. Given that users new to Linux are prone to spend a considerable amount of time familiarizing themselves with basic userspace tools, setting up a comfortable environment is a necessity to most.

There are two prevalent methods for achieving colored man pages: using most, or opting for less. The former is simpler to configure, at the expense of the advanced functionality that is native to less.

First method: using 'most'

Install Template:Package Official using pacman:

# pacman -S most

This is similar to less and more, yet allows rendering colored text in an easier way.

Edit Template:Filename, uncomment the pager definition and change it to:

DEFINE     pager     most -s

Test the new setup by typing:

$ man whatever_man_page

Modifying the color values requires editing Template:Filename (creating the file if it is not present) or editing Template:Filename for system-wide changes. Example Template:Filename:

% Color settings
color normal lightgray black
color status yellow blue
color underline yellow black
color overstrike brightblue black

Another example showing keybindings similar to less (jump to line is set to 'J'):

% less-like keybindings
unsetkey "^K"
unsetkey "g"
unsetkey "G"
unsetkey ":"

setkey next_file ":n"
setkey find_file ":e"
setkey next_file ":p"
setkey toggle_options ":o"
setkey toggle_case ":c"
setkey delete_file ":d"
setkey exit ":q"

setkey bob "g"
setkey eob "G"
setkey down "e"
setkey down "E"
setkey down "j"
setkey down "^N"
setkey up "y"
setkey up "^Y"
setkey up "k"
setkey up "^P"
setkey up "^K"
setkey page_down "f"
setkey page_down "^F"
setkey page_up "b"
setkey page_up "^B"
setkey other_window "z"
setkey other_window "w"
setkey search_backward "?"
setkey bob "p"
setkey goto_mark "'"
setkey find_file "E"
setkey edit "v"

Second method: using 'less'

Source: nion's blog - less colors for man pages

Alternatively, getting an approximate coloured result in manual pages with less is also a possibility. This method has the advantage that less has a bigger feature set than most, and that might be the preference for advanced users.

Add the following to a shell configuration file. For Bash it would be Template:Filename:

man() {
	env \
		LESS_TERMCAP_mb=$(printf "\e[1;31m") \
		LESS_TERMCAP_md=$(printf "\e[1;31m") \
		LESS_TERMCAP_me=$(printf "\e[0m") \
		LESS_TERMCAP_se=$(printf "\e[0m") \
		LESS_TERMCAP_so=$(printf "\e[1;44;33m") \
		LESS_TERMCAP_ue=$(printf "\e[0m") \
		LESS_TERMCAP_us=$(printf "\e[1;32m") \
			man "$@"
}

To customize the colors, see Wikipedia:ANSI escape code for reference.

Colored man pages on xterm or rxvt-unicode

Source:XFree resources file for XTerm program

A quick way to add color to manual pages viewed on Template:Package Official/uxterm or Template:Package Official can be made modifying the Template:Filename file.

Note: If Template:Filename does not work for you, you can try using Template:Filename.

Open that file in an editor and add this lines:

(For xterm)

*VT100.colorBDMode:     true
*VT100.colorBD:         red
*VT100.colorULMode:     true
*VT100.colorUL:         cyan

(For rxvt-unicode)

URxvt.colorIT:      #87af5f
URxvt.colorBD:      #d7d7d7
URxvt.colorUL:      #87afd7

Save and run:

$ xrdb -load ~/.Xresources

Launch a new xterm/uxterm or rxvt-unicode and you should see colorful man pages. This combination puts colors to bold and underlined words in xterm/uxterm or to bold, underlined, and italicized text in rxvt-unicode. You can play with different combinations of this attributes (see the sources of this item).

Reading man pages with a browser

Instead of the standard interface, using browsers such as lynx and Firefox to view man pages allows users to reap info pages' main benefit: hyperlinked text. Additionally, KDE users can read man pages in Konqueror using:

man:<name>

Using Local Man Pages

First, install Template:Package AUR from the AUR.

Now, convert a man page:

$ man free | man2html -compress -cgiurl man$section/$title.$section$subsection.html > ~/man/free.html

Another use for man2html is exporting to raw, printer-friendly text:

$ man free | man2html -bare > ~/free.txt

The GNU implementation of man in the Arch repositories also has the ability to do this on its own:

$ man -H free

This will read your BROWSER environment variable to determine the browser. You can override this by passing the binary to the -H option.

Using Online Man Pages

There are several online databases of man pages, including: