Difference between revisions of "Man page"
(Edited man() function to use Arch/Gentoo colours) |
m (→Online man pages: use HTTPS & flag dead links) |
||
(114 intermediate revisions by 36 users not shown) | |||
Line 1: | Line 1: | ||
− | [[Category: | + | {{Lowercase title}} |
− | [[ar:Man | + | [[Category:Command-line]] |
− | [[ko:Man | + | [[ar:Man page]] |
− | [[ru:Man | + | [[es:Man page]] |
− | [[zh- | + | [[id:Man page]] |
− | {{ | + | [[ja:Man ページ]] |
− | {{ | + | [[ko:Man page]] |
− | + | [[pt:Man page]] | |
− | {{ | + | [[ru:Man page]] |
− | + | [[zh-hans:Man page]] | |
− | + | {{Related articles start}} | |
− | + | {{Related|Color output in console#man}} | |
− | + | {{Related articles end}} | |
− | + | [[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 files, GNU's attempt at replacing the traditional man page format. | ||
− | ==Accessing | + | {{Pkg|man-db}} implements ''man'' on Arch Linux, and [[Core utilities#less|less]] is the default pager used with ''man''. |
+ | |||
+ | == 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 | + | 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}}. |
− | # | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | 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 | + | 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 31: | ||
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. | ||
− | + | 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 == | |
− | + | 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}}. | |
− | == | + | == 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. | |
− | |||
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 everytime a new manpage is installed. | ||
Line 79: | Line 68: | ||
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 | ||
− | == | + | == Page width == |
− | + | The man page width is controlled by the {{Ic|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 {{Ic|man}} invocation. With {{Ic|Bash}}, that would be: | |
− | |||
− | |||
− | + | {{Hc|~/.bashrc|<nowiki> | |
− | {{ | + | man() { |
− | <nowiki>man() { | + | local width=$(tput cols) |
− | + | [ $width -gt $MANWIDTH ] && width=$MANWIDTH | |
− | + | env MANWIDTH=$width \ | |
− | |||
− | |||
− | |||
− | |||
− | |||
man "$@" | man "$@" | ||
} | } | ||
</nowiki>}} | </nowiki>}} | ||
− | + | == Reading local man pages == | |
− | + | 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: | |
− | |||
− | |||
− | |||
− | + | * [[KDE]] users can read man pages in | |
− | + | ** Konqueror using {{ic|man:<name>}}. | |
− | + | ** KHelpCenter ({{Pkg|khelpcenter}}) in "UNIX manual pages" or by running {{ic|khelpcenter man:<name>}}. | |
− | + | * {{pkg|xorg-xman}} provides a categorized look at man pages in [[X]]. | |
+ | * The [[GNOME]] Help Browser {{pkg|yelp}} can be used via {{ic|yelp man:<name>}}. | ||
− | + | === Conversion to HTML === | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | === | + | ==== mandoc ==== |
− | + | Install the {{AUR|mandoc}} package. To convert a page, for example {{ic|free(1)}}: | |
− | + | $ gunzip -c /usr/share/man/man1/free.1.gz | mandoc -Thtml -Ostyle=style.css 1> free.html | |
− | + | Now open the file called {{ic|free.html}} in your favourite browser. | |
− | |||
− | |||
− | |||
− | |||
− | + | ==== man2html ==== | |
− | + | First, install {{Pkg|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 {{Ic|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 {{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]]. | |
− | |||
− | + | To convert a man page: | |
− | |||
− | + | $ gunzip -c /usr/share/man/man1/free.1.gz | roffit > free.html | |
− | $ man | ||
− | + | === 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, 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. | 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. | 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: |
− | + | * [http://man7.org/linux/man-pages/index.html man7.org]. Upstream for Arch Linux's {{pkg|man-pages}}. | |
− | + | * [https://jlk.fjfi.cvut.cz/arch/manpages/ Arch Linux man pages]. Used for links from the wiki. | |
+ | * [https://manned.org/ manned.org's collection from various Linux distributions, BSD, etc., with multiple package versions] | ||
+ | * [https://manpages.debian.net/ Debian GNU/Linux man pages] | ||
+ | * [https://leaf.dragonflybsd.org/cgi/web-man DragonFlyBSD manual pages] | ||
+ | * [https://www.freebsd.org/cgi/man.cgi FreeBSD man pages] | ||
+ | * [http://www.manpages.spotlynx.com/ Linux and Solaris 10 man pages]{{Dead link|2018|04|16}} | ||
+ | * [https://linux.die.net/man/ Linux man pages at die.net] | ||
+ | * [https://man.cx/ Linux man pages at man.cx] | ||
+ | * [http://netbsd.gw.com/cgi-bin/man-cgi NetBSD manual pages] | ||
+ | * [https://developer.apple.com/documentation/Darwin/Reference/ManPages/index.html Mac OS X manual pages] | ||
+ | * [http://unixhelp.ed.ac.uk/alphabetical/index.html On-line UNIX manual pages]{{Dead link|2018|04|16}} | ||
+ | * [https://www.openbsd.org/cgi-bin/man.cgi OpenBSD manual pages] | ||
+ | * [http://man.cat-v.org/plan_9/ Plan 9 Manual — Volume 1] | ||
+ | * [http://man.cat-v.org/inferno/ Inferno Manual — Volume 1] | ||
+ | * [http://sfdoccentral.symantec.com/sf/5.0MP3/linux/manpages/index.html Storage Foundation man pages] | ||
+ | * [https://www.unix.com/man-page/OpenSolaris/1/man/ The UNIX and Linux forums man page repository] | ||
+ | * [http://manpages.ubuntu.com/ Ubuntu manpage repository] | ||
− | + | {{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). | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | + | * {{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]: | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
$ man -s 7 -k ".*" | $ man -s 7 -k ".*" | ||
Arch Linux specific pages: | Arch Linux specific pages: | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | ==See also== | + | * {{man|7|archlinux}} |
+ | * {{man|8|mkinitcpio}} | ||
+ | * {{man|8|pacman}} | ||
+ | * {{man|8|pacman-key}} | ||
+ | * {{man|5|pacman.conf}} | ||
+ | |||
+ | == See also == | ||
− | * [[ | + | * [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 17:24, 16 April 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 files, 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.
Contents
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
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 everytime a new manpage 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
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:
- KDE users can read man pages in
- Konqueror using
man:<name>
. - KHelpCenter (khelpcenter) in "UNIX manual pages" or by running
khelpcenter man:<name>
.
- Konqueror using
- xorg-xman provides a categorized look at man pages in X.
- The GNOME Help Browser yelp can be used via
yelp man:<name>
.
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, converting a man page to PDF is actually very easy: man -t <manpage> | ps2pdf - <pdf>
. 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.
Online man pages
There are several online databases of man pages, including:
- man7.org. Upstream for Arch Linux's man-pages.
- Arch Linux man pages. Used for links from the wiki.
- manned.org's collection from various Linux distributions, BSD, etc., with multiple package versions
- Debian GNU/Linux man pages
- DragonFlyBSD manual pages
- FreeBSD man pages
- Linux and Solaris 10 man pages[dead link 2018-04-16]
- Linux man pages at die.net
- Linux man pages at man.cx
- NetBSD manual pages
- Mac OS X manual pages
- On-line UNIX manual pages[dead link 2018-04-16]
- OpenBSD manual pages
- Plan 9 Manual — Volume 1
- Inferno Manual — Volume 1
- Storage Foundation man pages
- The UNIX and Linux forums man page repository
- Ubuntu manpage repository
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).
- ascii(7)
- boot(7)
- charsets(7)
- chmod(1)
- credentials(7)
- fstab(5)
- hier(7)
- systemd(1)
- locale(1p), locale(5), locale(7)
- printf(3)
- proc(5)
- regex(7)
- signal(7)
- term(5), term(7)
- termcap(5)
- terminfo(5)
- utf-8(7)
More generally, have a look at category 7 (miscellaneous) pages:
$ man -s 7 -k ".*"
Arch Linux specific pages: