Difference between revisions of "Man page"

From ArchWiki
Jump to: navigation, search
(Online Man Pages: Added link for the man7.org manual pages as it is used for arch linux's package. Removing dead link as still dead since the end of July and looks like the domain has expired.)
m (fix link)
 
(129 intermediate revisions by 42 users not shown)
Line 1: Line 1:
[[Category:System administration]]
+
{{Lowercase title}}
[[ar:Man Page]]
+
[[Category:Command-line]]
[[ko:Man Page]]
+
[[ar:Man page]]
[[ru:Man Page]]
+
[[es:Man page]]
[[zh-CN:Man Page]]
+
[[id:Man page]]
{{Article summary start|Summary}}
+
[[ja:Man ページ]]
{{Article summary text|Information on man pages, along with recommendations on how to improve their usage}}
+
[[ko:Man page]]
<!--
+
[[pt:Man page]]
{{Article summary heading|Related}}
+
[[ru:Man page]]
{{Article summary wiki|}}
+
[[zh-hans:Man page]]
-->
+
{{Related articles start}}
{{Article summary end}}
+
{{Related|Color output in console#man}}
{{DISPLAYTITLE:man pages}}
+
{{Related articles 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 {{Ic|man}}.
+
[[Wikipedia:Man_page|man pages]]—abbreviation for "manual pages"—are the form of documentation that is available on almost all 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 manual|Info documents]], GNU's attempt at replacing the traditional man page format.
 +
 
 +
{{Pkg|man-db}} implements ''man'' on Arch Linux, and [[Core utilities#Essentials|less]] is the default pager used with ''man''.
 +
 
 +
== Accessing man pages ==
  
==Accessing Man Pages==
 
 
To read a man page, simply enter:
 
To read a man page, simply enter:
  
 
  $ man ''page_name''
 
  $ man ''page_name''
  
Manuals are sorted into several sections:
+
Manuals are sorted into several [[Wikipedia:Man_page#Manual_sections|sections]]. For a full listing see the section entitled "Sections of the manual pages" in {{man|7|man-pages}}.
# General commands
 
# System calls (functions provided by the kernel)
 
# Library calls (C library functions)
 
# Special files (usually found in /dev) and drivers
 
# File formats and conventions
 
# Games
 
# Miscellaneous (including conventions)
 
# 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 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|man}} and {{man|7|man}}. In this case, give man the section number followed by the name of the man page, for example:
  
 
  $ man 5 passwd
 
  $ man 5 passwd
Line 37: Line 32:
 
to read the man page on {{Ic|/etc/passwd}}, rather than the {{Ic|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 {{Ic|whatis}} command. For example, for a brief description of ls, type:
+
One-line descriptions of man pages can be displayed using the {{Ic|whatis}} command. For example, for a brief description of the man page sections about {{ic|ls}}, type:
 +
 
 +
{{hc|$ whatis ls|
 +
ls (1p)              - list directory contents
 +
ls (1)              - list directory contents
 +
}}
 +
 
 +
== Format ==
  
$ whatis ls
+
Man pages all follow a fairly standard format, which helps in navigating them. See the section entitled "Sections within a manual page" in {{man|7|man-pages}}.
  
and {{Ic|whatis}} will output "list directory contents."
+
== Searching manuals ==
  
==Format==
+
{{Style|Unnecessarily verbose.}}
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==
+
Even though the {{Ic|man}} utility allows users to display man pages, and search their contents via ''less'', 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.
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.
 
  
 
The research feature is provided by a dedicated cache. By default you may not have any cache built and all your searches will give you the ''nothing appropriate'' result. You can generate the cache or update it by running
 
The research feature is provided by a dedicated cache. By default you may not have any cache built and all your searches will give you the ''nothing appropriate'' result. You can generate the cache or update it by running
 +
 
  # mandb
 
  # mandb
You should run it everytime a new manpage is installed.
+
 
 +
You should run it every time a new man page is installed.
  
 
Now you can begin your search.
 
Now you can begin your search.
Line 72: Line 64:
 
  $ man --apropos password
 
  $ man --apropos password
  
This is equivalent to calling the {{Ic|apropos}} command:
+
This is equivalent to calling the {{ic|apropos}} command:
  
 
  $ apropos password
 
  $ apropos password
Line 79: Line 71:
  
 
If you want to do a more in-depth search by matching the keywords found in the whole articles, you can use the {{ic|-K}} option:
 
If you want to do a more in-depth search by matching the keywords found in the whole articles, you can use the {{ic|-K}} option:
 +
 
  $ man -K password
 
  $ man -K password
  
==Colored man pages==
+
== Page width ==
Color-enabled man pages allow for a clearer presentation and easier digestion of the content.
+
The man page width is controlled by the {{Ic|MANWIDTH}} environment variable.
There are two prevalent methods for achieving colored man pages: using {{Ic|less}}, or opting for {{Ic|most}}.
 
  
===Using {{ic|less}} (Recommended) ===
+
If the number of columns in the terminal is too small (e.g. the window width is narrow), the line breaks will be wrong. This can be very disturbing for reading. You can fix this by setting the MANWIDTH on {{Ic|man}} invocation. With {{Ic|Bash}}, that would be:
:<small>''Source: [http://nion.modprobe.de/blog/archives/572-less-colors-for-man-pages.html nion's blog - less colors for man pages]''</small>
 
This method has the advantage that {{Ic|less}} has a bigger feature set than {{Ic|most}}, and is the default for viewing man pages.
 
  
Add the following to a shell configuration file. For [[Bash]] it would be:
+
{{Hc|~/.bashrc|<nowiki>
{{hc|~/.bashrc|
+
man() {
<nowiki>man() {
+
     local width=$(tput cols)
     env LESS_TERMCAP_mb=$(printf "\e[1;31m") \
+
    [ $width -gt $MANWIDTH ] && width=$MANWIDTH
LESS_TERMCAP_md=$(printf "\e[1;31m") \
+
    env MANWIDTH=$width \
LESS_TERMCAP_me=$(printf "\e[0m") \
+
    man "$@"
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 "$@"
 
 
}
 
}
 
</nowiki>}}
 
</nowiki>}}
  
To customize the colors, see [[Wikipedia:ANSI escape code]] for reference.
+
== Reading local man pages ==
 
 
===Using {{ic|most}} (Not recommended)===
 
The basic function of 'most' is similar to {{Ic|less}} and {{Ic|more}}, but it has a smaller feature set. Configuring most to use colors is easier than using less, but additional configuration is necessary to make most behave like less.
 
Install {{Pkg|most}} using [[pacman]]:
 
# pacman -S most
 
 
 
Edit {{ic|/etc/man_db.conf}}, 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 {{ic|~/.mostrc}} (creating the file if it is not present) or editing {{ic|/etc/most.conf}} for system-wide changes. Example {{ic|~/.mostrc}}:
 
% Color settings
 
color normal lightgray black
 
color status yellow blue
 
color underline yellow black
 
color overstrike brightblue black
 
Another example showing keybindings similar to {{Ic|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"
 
 
 
=== Colored man pages on xterm or rxvt-unicode ===
 
 
 
:<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 {{Pkg|xterm}}/{{Ic|uxterm}} or {{Pkg|rxvt-unicode}} is to modify {{ic|~/.Xresources}}.
 
 
 
==== xterm ====
 
*VT100.colorBDMode:    true
 
*VT100.colorBD:        red
 
*VT100.colorULMode:    true
 
*VT100.colorUL:        cyan
 
  
which ''replaces'' the decorations with the colors. Also add:
+
{{Style|1=Sentence doesn't make sense. Man pages != info pages.}}
  
*VT100.veryBoldColors: 6
+
Instead of the standard interface, using browsers such as {{Pkg|lynx}} and [[Firefox]] to view man pages allows users to reap info pages' main benefit of hyperlinked text. Alternatives include the following:
  
if you want colors and decorations (bold or underline) ''at the same time''.  See {{ic|man xterm}} for a description of the {{ic|veryBoldColors}} resource.
+
=== Viewer applications ===
  
==== rxvt-unicode ====
+
* {{App|GNOME Help|Help viewer for [[GNOME]]. It can show man pages via {{ic|yelp man:<name>}}.|https://wiki.gnome.org/Apps/Yelp|{{Pkg|yelp}}}}
URxvt.colorIT:     #87af5f
+
* {{App|KHelpCenter|Application to show [[KDE]] Applications' documentation. Man pages are in ''UNIX manual pages'' or by running {{ic|khelpcenter man:<name>}}.|https://userbase.kde.org/KHelpCenter|{{Pkg|khelpcenter}}}}
URxvt.colorBD:     #d7d7d7
+
* {{App|[[Wikipedia:Konqueror|Konqueror]]|KDE file manager and web browser. It can show man pages via {{ic|man:<name>}}.|https://konqueror.org/|{{Pkg|konqueror}}}}
URxvt.colorUL:     #87afd7
+
* {{App|xman|Provides a categorized look at man pages.|https://xorg.freedesktop.org/|{{pkg|xorg-xman}}}}
  
Run:
+
=== Conversion to HTML ===
$ xrdb -load ~/.Xresources
 
  
Launch a new {{Ic|xterm/uxterm}} or {{Ic|rxvt-unicode}} and you should see colorful man pages.
+
==== mandoc ====
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 these attributes (see the [http://pub.ligatura.org/fs/xfree86/xresources/xterm sources] of this item).
 
  
== Reading local man pages ==
+
Install the {{AUR|mandoc}} package. To convert a page, for example {{ic|free(1)}}:
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.
 
  
[[KDE]] users can read man pages in Konqueror using:
+
  $ gunzip -c /usr/share/man/man1/free.1.gz | mandoc -Thtml -Ostyle=style.css 1> free.html
  man:<name>
 
From the [[Official Repositories]] come two other possibilities:
 
  
1. {{pkg|xorg-xman}} provides a categorized look at man pages in [[X]].
+
Now open the file called {{ic|free.html}} in your favourite browser.
  
2. The [[GNOME]] Help Browser {{pkg|yelp}} is a more neat way but has some dependencies.
+
==== man2html ====
  
=== Converting to browser-readable HTML ===
 
 
First, install {{Pkg|man2html}} from the official repositories.
 
First, install {{Pkg|man2html}} from the official repositories.
  
 
Now, convert a man page:
 
Now, convert a man page:
 +
 
  $ 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 {{Ic|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
 +
 +
==== man -H ====
  
 
The GNU implementation of man in the Arch repositories also has the ability to do this on its own:
 
The GNU implementation of man in the Arch repositories also has the ability to do this on its own:
 +
 
  $ man -H free
 
  $ man -H free
  
This will read your {{ic|BROWSER}} environment variable to determine the browser. You can override this by passing the binary to the {{ic|-H}} option.
+
This will read your {{ic|BROWSER}} [[environment variable]] to determine the browser. You can override this by passing the binary to the {{ic|-H}} option.
 +
 
 +
==== roffit ====
 +
 
 +
First install {{AUR|roffit}} from [[AUR]].
  
=== Converting to PDF ===
+
To convert a man page:
man pages have always been printable: they are written in troff, which is fundamentally a typesetting language. If you have ghostscript installed, converting a man page to PDF is actually very easy: {{ic|<nowiki>man -t <manpage> | ps2pdf - <pdf></nowiki>}}. [https://www.google.com/search?q=manpage+pdf+troff&num=100&hl=en&prmd=imvns&source=lnms&tbm=isch&sa=X&ei=5BZpUI3oH6rI2AXvx4CoAw&ved=0CAoQ_AUoAQ&biw=1321&bih=1100 This google image search] should give you an idea of what the result looks like; it may not be to everybody's liking.
 
  
Caveats: Fonts are generally limited to Times at hardcoded sizes. There are no hyperlinks. Some man pages were specifically designed for terminal viewing, and won't look right in PS or PDF form.
+
$ gunzip -c /usr/share/man/man1/free.1.gz | roffit > free.html
  
The following perl script converts man pages to PDFs, caches the PDFs in the {{ic|$HOME/.manpdf/}} directory, and calls a PDF viewer, specifically [https://www.archlinux.org/packages/community/x86_64/mupdf/ mupdf].
+
=== Conversion to PDF ===
  
{{hc|Usage: manpdf [<section>] <manpage>|<nowiki>
+
man pages have always been printable: they are written in troff, which is fundamentally a typesetting language. If you have {{Pkg|ghostscript}} installed, you can convert a man page to PDF using {{ic|man -t <manpage> {{!}} ps2pdf - <pdf>}}.
#!/usr/bin/perl
 
use File::stat;
 
  
$pdfdir = $ENV{"HOME"}."/.manpdf";
+
Caveats: Fonts are generally limited to Times at hardcoded sizes. There are no hyperlinks. Some man pages were specifically designed for terminal viewing, and won't look right in PS or PDF form.
-d $pdfdir || mkdir $pdfdir || die "can't create $pdfdir";
 
$manpage = $ARGV[0];
 
chop($manpath = `man -w $manpage`);
 
die if $?;
 
  
$maninfo = stat($manpath) or die;
+
== Online man pages ==
$manpath =~ s@.*/man./(.*)(\.(gz|bz2))?$@$1@;
 
$pdfpath = "$pdfdir/$manpath.pdf";
 
$pdftime = 0;
 
if (-f $pdfpath) {
 
    $pdfinfo = stat($pdfpath) or die;
 
    $pdftime = $pdfinfo->mtime;
 
}
 
if (!-f $pdfpath || $maninfo->mtime > $pdftime) {
 
    system "man -t $manpage | ps2pdf -dPDFSETTINGS=/screen - $pdfpath";
 
}
 
die if !-f $pdfpath;
 
if (!fork) {
 
    open(STDOUT, "/dev/null");
 
    open(STDERR, "/dev/null");
 
    exec "mupdf", "-r", "96", $pdfpath;
 
    #exec "acroread", $pdfpath;
 
}
 
</nowiki>}}
 
  
== Online Man Pages ==
 
 
There are several online databases of man pages, including:
 
There are several online databases of man pages, including:
*[http://man7.org/linux/man-pages/index.html Man7.org.] Upstream for Arch Linux's {{pkg|man-pages}}.
+
* [http://man7.org/linux/man-pages/index.html man7.org]. Upstream for Arch Linux's {{pkg|man-pages}}.
*[http://manpages.debian.net/ ''Debian GNU/Linux man pages'']
+
* [https://jlk.fjfi.cvut.cz/arch/manpages/ Arch Linux man pages].  Used for links from the wiki.
*[http://leaf.dragonflybsd.org/cgi/web-man ''DragonFlyBSD manual pages'']
+
* [https://manned.org/ manned.org's collection from various Linux distributions, BSD, etc., with multiple package versions]
*[http://www.freebsd.org/cgi/man.cgi ''FreeBSD Hypertext Man Pages'']
+
* [https://manpages.debian.net/ Debian GNU/Linux man pages]
*[http://www.manpages.spotlynx.com/ ''Linux and Solaris 10 Man Pages'']
+
* [https://leaf.dragonflybsd.org/cgi/web-man DragonFlyBSD manual pages]
*[http://manpagehelp.net ''Linux/FreeBSD Man Pages''] with user comments
+
* [https://www.freebsd.org/cgi/man.cgi FreeBSD man pages]
*[http://linux.die.net/man/ ''Linux man pages at die.net'']
+
* [http://www.manpages.spotlynx.com/ Linux and Solaris 10 man pages]{{Dead link|2018|04|16}}
*[http://www.kernel.org/doc/man-pages/ The Linux man-pages project at kernel.org]
+
* [https://linux.die.net/man/ Linux man pages at die.net]
*[http://netbsd.gw.com/cgi-bin/man-cgi ''NetBSD manual pages'']
+
* [https://man.cx/ Linux man pages at man.cx]
*[http://developer.apple.com/documentation/Darwin/Reference/ManPages/index.html ''Mac OS X Manual Pages'']
+
* [http://netbsd.gw.com/cgi-bin/man-cgi NetBSD manual pages]
*[http://unixhelp.ed.ac.uk/alphabetical/index.html ''On-line UNIX manual pages'']
+
* [https://developer.apple.com/documentation/Darwin/Reference/ManPages/index.html Mac OS X manual pages]
*[http://www.openbsd.org/cgi-bin/man.cgi ''OpenBSD manual pages'']
+
* [http://unixhelp.ed.ac.uk/alphabetical/index.html On-line UNIX manual pages]{{Dead link|2018|04|16}}
*[http://man.cat-v.org/plan_9/ ''Plan 9 Manual — Volume 1'']
+
* [https://www.openbsd.org/cgi-bin/man.cgi OpenBSD manual pages]
*[http://man.cat-v.org/inferno/ ''Inferno Manual — Volume 1'']
+
* [http://man.cat-v.org/plan_9/ Plan 9 Manual — Volume 1]
*[http://sfdoccentral.symantec.com/sf/5.0MP3/linux/manpages/index.html ''Storage Foundation Man Pages'']
+
* [http://man.cat-v.org/inferno/ Inferno Manual — Volume 1]
*[http://www.unix.com/man-page/OpenSolaris/1/man/ ''The UNIX and Linux Forums Man Page Repository'']
+
* [http://sfdoccentral.symantec.com/sf/5.0MP3/linux/manpages/index.html Storage Foundation man pages]
*[http://manpages.ubuntu.com/ ''Ubuntu Manpage Repository'']
+
* [https://www.unix.com/man-page/OpenSolaris/1/man/ The UNIX and Linux forums man page repository]
 +
* [http://manpages.ubuntu.com/ Ubuntu manpage repository]
 +
 
 +
{{Tip|You can use the {{ic|!archman}} DuckDuckGo [https://duckduckgo.com/bang.html !Bang] to search through the [https://jlk.fjfi.cvut.cz/arch/manpages/ Arch Linux man pages] directly.}}
 +
{{Warning|Some distributions provide patched or outdated man pages that differ from those provided by Arch. Exercise caution when using online man pages.}}
  
 
==Noteworthy manpages==
 
==Noteworthy manpages==
  
Here follows a non-exhaustive list of noteworthy pages that might help you understand a lot of things more in-depth. Some of them might serve as a good reference (like the ascii table).
+
Here follows a non-exhaustive list of noteworthy pages that might help you understand a lot of things more in-depth. Some of them might serve as a good reference (like the ASCII table).
 +
 
 +
* {{man|7|ascii}}
 +
* {{man|7|boot}}
 +
* {{man|7|charsets}}
 +
* {{man|1|chmod}}
 +
* {{man|7|credentials}}
 +
* {{man|5|fstab}}
 +
* {{man|7|hier}}
 +
* {{man|1|systemd}}
 +
* {{man|1p|locale}}, {{man|5|locale}}, {{man|7|locale}}
 +
* {{man|3|printf}}
 +
* {{man|5|proc}}
 +
* {{man|7|regex}}
 +
* {{man|7|signal}}
 +
* {{man|5|term}}, {{man|7|term}}
 +
* {{man|5|termcap}}
 +
* {{man|5|terminfo}}
 +
* {{man|7|utf-8}}
 +
 
 +
More generally, have a look at [http://man7.org/linux/man-pages/dir_section_7.html category 7 (miscellaneous) pages]:
  
* ascii(7)
 
* boot(7)
 
* charsets(7)
 
* chmod(1)
 
* credentials(7)
 
* fstab(5)
 
* hier(7)
 
* systemd(1)
 
* locale(1P)(5)(7)
 
* printf(3)
 
* proc(5)
 
* regex(7)
 
* signal(7)
 
* term(5)(7)
 
* termcap(5)
 
* terminfo(5)
 
* utf-8(7)
 
More generally, have a look at category 7 pages:
 
 
  $ man -s 7 -k ".*"  
 
  $ man -s 7 -k ".*"  
  
 
Arch Linux specific pages:
 
Arch Linux specific pages:
* archlinux(7)
 
* mkinitcpio(8)
 
* pacman(8)
 
* pacman-key(8)
 
* pacman.conf(5)
 
  
==See also==
+
* {{man|7|archlinux}}
 +
* {{man|8|mkinitcpio}}
 +
* {{man|8|pacman}}
 +
* {{man|8|pacman-key}}
 +
* {{man|5|pacman.conf}}
 +
 
 +
== See also ==
  
* [[General Recommendations]] - General Recommendations for Arch
+
* [https://wiki.gentoo.org/wiki/Man_page man page - Gentoo wiki article]
 +
* [https://linuxtidbits.wordpress.com/2013/08/21/wtfm-write-the-fine-manual-with-pod2man-text-converter/ Write The Fine Manual with pod2man]

Latest revision as of 13:01, 28 September 2018

man pages—abbreviation for "manual pages"—are the form of documentation that is available on almost all 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 documents, GNU's attempt at replacing the traditional man page format.

man-db implements man on Arch Linux, and less is the default pager used with man.

Accessing man pages

To read a man page, simply enter:

$ man page_name

Manuals are sorted into several sections. For a full listing see the section entitled "Sections of the manual pages" in man-pages(7).

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.

One-line descriptions of man pages can be displayed using the whatis command. For example, for a brief description of the man page sections about ls, type:

$ whatis ls
ls (1p)              - list directory contents
ls (1)               - list directory contents

Format

Man pages all follow a fairly standard format, which helps in navigating them. See the section entitled "Sections within a manual page" in man-pages(7).

Searching manuals

Tango-edit-clear.pngThis article or section needs language, wiki syntax or style improvements. See Help:Style for reference.Tango-edit-clear.png

Reason: Unnecessarily verbose. (Discuss in Talk:Man page#)

Even though the man utility allows users to display man pages, and search their contents via less, 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.

The research feature is provided by a dedicated cache. By default you may not have any cache built and all your searches will give you the nothing appropriate result. You can generate the cache or update it by running

# mandb

You should run it every time a new man page is installed.

Now you can begin your search. 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.

If you want to do a more in-depth search by matching the keywords found in the whole articles, you can use the -K option:

$ man -K password

Page width

The man page width is controlled by the MANWIDTH environment variable.

If the number of columns in the terminal is too small (e.g. the window width is narrow), the line breaks will be wrong. This can be very disturbing for reading. You can fix this by setting the MANWIDTH on man invocation. With Bash, that would be:

~/.bashrc
man() {
    local width=$(tput cols)
    [ $width -gt $MANWIDTH ] && width=$MANWIDTH
    env MANWIDTH=$width \
    man "$@"
}

Reading local man pages

Tango-edit-clear.pngThis article or section needs language, wiki syntax or style improvements. See Help:Style for reference.Tango-edit-clear.png

Reason: Sentence doesn't make sense. Man pages != info pages. (Discuss in Talk:Man page#)

Instead of the standard interface, using browsers such as lynx and Firefox to view man pages allows users to reap info pages' main benefit of hyperlinked text. Alternatives include the following:

Viewer applications

  • GNOME Help — Help viewer for GNOME. It can show man pages via yelp man:<name>.
https://wiki.gnome.org/Apps/Yelp || yelp
  • KHelpCenter — Application to show KDE Applications' documentation. Man pages are in UNIX manual pages or by running khelpcenter man:<name>.
https://userbase.kde.org/KHelpCenter || khelpcenter
  • Konqueror — KDE file manager and web browser. It can show man pages via man:<name>.
https://konqueror.org/ || konqueror
  • xman — Provides a categorized look at man pages.
https://xorg.freedesktop.org/ || xorg-xman

Conversion to HTML

mandoc

Install the mandocAUR package. To convert a page, for example free(1):

$ gunzip -c /usr/share/man/man1/free.1.gz | mandoc -Thtml -Ostyle=style.css 1> free.html

Now open the file called free.html in your favourite browser.

man2html

First, install man2html from the official repositories.

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

man -H

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.

roffit

First install roffitAUR from AUR.

To convert a man page:

$ gunzip -c /usr/share/man/man1/free.1.gz | roffit > free.html

Conversion to PDF

man pages have always been printable: they are written in troff, which is fundamentally a typesetting language. If you have ghostscript installed, you can convert a man page to PDF using man -t <manpage> | ps2pdf - <pdf>.

Caveats: Fonts are generally limited to Times at hardcoded sizes. There are no hyperlinks. Some man pages were specifically designed for terminal viewing, and won't look right in PS or PDF form.

Online man pages

There are several online databases of man pages, including:

Tip: You can use the !archman DuckDuckGo !Bang to search through the Arch Linux man pages directly.
Warning: Some distributions provide patched or outdated man pages that differ from those provided by Arch. Exercise caution when using online man pages.

Noteworthy manpages

Here follows a non-exhaustive list of noteworthy pages that might help you understand a lot of things more in-depth. Some of them might serve as a good reference (like the ASCII table).

More generally, have a look at category 7 (miscellaneous) pages:

$ man -s 7 -k ".*" 

Arch Linux specific pages:

See also