Man page: Difference between revisions

From ArchWiki
(→‎Format: Duplicate, already covered in "Accessing man pages")
(Added Gnu Emacs to the list of programs that can read man pages.)
 
(63 intermediate revisions by 24 users not shown)
Line 1: Line 1:
{{Lowercase title}}
{{Lowercase title}}
[[Category:Command-line]]
[[Category:Command-line]]
[[ar:Man page]]
[[de:Manpages]]
[[es:Man page]]
[[es:Man page]]
[[id:Man page]]
[[id:Man page]]
[[ja:Man ページ]]
[[ja:Man ページ]]
[[ko:Man page]]
[[pt:Man page]]
[[pt:Man page]]
[[ru:Man page]]
[[ru:Man page]]
Line 18: Line 17:
== Installation ==
== Installation ==


{{Pkg|man-db}} implements ''man'' on Arch Linux, and [[Core utilities#Essentials|less]] is the default pager used with ''man''.
{{Pkg|man-db}} implements ''man'' on Arch Linux, and [[less]] is the default pager used with ''man''. {{Pkg|mandoc}} can also be used.


{{Pkg|man-pages}} provides the Linux man pages.
{{Pkg|man-pages}} provides both the Linux and the POSIX.1 man pages [https://gitlab.archlinux.org/archlinux/packaging/packages/man-pages/-/blob/main/PKGBUILD#L13-14].


Some localized man pages are also available:
Some localized man pages are also available:


* {{Pkg|man-pages-cs}} for Czech
* {{Pkg|man-pages-cs}} for Czech
* {{Pkg|man-pages-da}} for Danish
* {{Pkg|man-pages-de}} for German
* {{Pkg|man-pages-de}} for German
* {{Pkg|man-pages-el}} for Greek
* {{Pkg|man-pages-es}} for Spanish
* {{Pkg|man-pages-fi}} for Finnish
* {{Pkg|man-pages-fr}} for French
* {{Pkg|man-pages-hu}} for Hungarian
* {{Pkg|man-pages-id}} for Indonesian
* {{Pkg|man-pages-it}} for Italian
* {{AUR|man-pages-ja}} for Japanese
* {{Pkg|man-pages-mk}} for Macedonian
* {{Pkg|man-pages-nl}} for Dutch
* {{Pkg|man-pages-pl}} for Polish
* {{Pkg|man-pages-pt_br}} for Brazilian Portuguese
* {{Pkg|man-pages-ro}} for Romanian
* {{Pkg|man-pages-ru}} for Russian
* {{Pkg|man-pages-sr}} for Serbian
* {{Pkg|man-pages-sv}} for Swedish
* {{AUR|man-pages-tr}} for Turkish
* {{Pkg|man-pages-uk}} for Ukranian
* {{Pkg|man-pages-vi}} for Vietnamese
* {{Pkg|man-pages-zh_cn}} for Simplified Chinese
* {{Pkg|man-pages-zh_cn}} for Simplified Chinese
* {{Pkg|man-pages-zh_tw}} for Traditional Chinese
* {{Pkg|man-pages-zh_tw}} for Traditional Chinese
You can also search for all of the available localized man pages [https://archlinux.org/packages/?sort=&q=man-pages- on the official repositories] and [https://aur.archlinux.org/packages?K=man-pages- on the AUR].


You can use some applications to view man pages:
You can use some applications to view man pages:


* {{App|GNOME Help|Help viewer for [[GNOME]]. It can show man pages via {{ic|yelp man:<name>}} or the undocumented {{ic|Ctrl+L}} keybinding from an existing window.|https://wiki.gnome.org/Apps/Yelp|{{Pkg|yelp}}}}
* {{App|GNOME Help|Help viewer for [[GNOME]]. Part of {{Grp|gnome}}. It can show man pages via {{ic|yelp man:<name>}} or the undocumented {{ic|Ctrl+L}} keybinding from an existing window.|https://wiki.gnome.org/Apps/Yelp|{{Pkg|yelp}}}}
* {{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}}}}
* {{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}}}}
* {{App|[[Wikipedia:Konqueror|Konqueror]]|KDE file manager and web browser. It can show man pages via {{ic|man:<name>}}.|https://konqueror.org/|{{Pkg|konqueror}}}}
* {{App|[[Wikipedia:Konqueror|Konqueror]]|KDE file manager and web browser. It can show man pages via {{ic|man:<name>}}.|https://konqueror.org/|{{Pkg|konqueror}}}}
* {{App|xman|Provides a categorized look at man pages.|https://xorg.freedesktop.org/|{{pkg|xorg-xman}}}}
* {{App|xman|Provides a categorized look at man pages.|https://xorg.freedesktop.org/|{{pkg|xorg-xman}}}}
* {{App|[[neovim]]|The editor can be used to read man pages using the built-in {{ic|:Man ''name''}} command, or configured as a man pager with {{ic|export MANPAGER{{=}}'nvim +Man!'}}. Supports highlighting and navigation between command-line flags, keywords, and other man pages. Automatically generates an outline using section headers, command-line flags, and keywords as entries (available via {{ic|gO}}).|https://neovim.io/|{{Pkg|neovim}}}}
* {{App|[[Emacs]]| The extensible and self-documenting editor can also be used to read man pages with the built-in M-x {{ic|man}} command.|https://www.gnu.org/software/emacs/|{{Pkg|emacs}}}}


== Accessing man pages ==
== Accessing man pages ==
Line 42: Line 65:
  $ man ''page_name''
  $ man ''page_name''


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}}.
Manuals are sorted into several [[Wikipedia:Man page#Manual sections|sections]]. Each section has an intro, such as {{man|1|intro}}, {{man|2|intro}} and so on. For a full listing see {{man|7|man-pages|Sections of the manual 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|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 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:
Line 49: Line 72:


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.
Or equivalently, the man page followed by the section number, separated by a period:
$ man passwd.5


== Searching manuals ==
== Searching manuals ==
Line 72: Line 99:


== Page width ==
== Page width ==
The man page width is controlled by the {{Ic|MANWIDTH}} environment variable.
The man page width is controlled by the {{Ic|MANWIDTH}} environment variable.


Line 93: Line 121:
==== mandoc ====
==== mandoc ====


Install the {{AUR|mandoc}} package. To convert a page, for example {{ic|free(1)}}:
Install the {{Pkg|mandoc}} package. To convert a page, for example {{ic|free(1)}}:


  $ mandoc -Thtml -Ostyle=style.css /usr/share/man/man1/free.1.gz > free.html
  $ mandoc -Thtml -Ostyle=style.css /usr/share/man/man1/free.1.gz > free.html
Line 113: Line 141:
==== man -H ====
==== man -H ====


The GNU implementation of man in the Arch repositories also has the ability to do this on its own:
The {{Pkg|man-db}} implementation also has the ability to do this on its own:


  $ man -H free
  $ man -H free
Line 121: Line 149:
==== roffit ====
==== roffit ====


First install {{AUR|roffit}} from [[AUR]].
First install {{AUR|roffit}}.


To convert a man page:
To convert a man page:
Line 129: Line 157:
=== Conversion to PDF ===
=== Conversion to PDF ===


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>}}.
man pages have always been printable: they are written in {{man|1|troff}}, which is fundamentally a typesetting language. Therefore, you can easily convert man pages to any of the formats supported as output devices by ''groff'', which is used by {{Pkg|man-db}}. For a list of output devices, see the {{ic|-T}} option in {{man|1|groff}} (or {{man|1|mandoc}} if you use the {{Pkg|mandoc}} package).
 
This will produce a PDF file:
 
$ man -Tpdf ''manpage'' > ''filename''


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. Some man pages were specifically designed for terminal viewing, and will not look right in PS or PDF form.


== Online man pages ==
== 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]—The Linux man-pages project. Upstream of the {{pkg|man-pages}} package.
 
* [https://jlk.fjfi.cvut.cz/arch/manpages/ Arch manual pages]—contains man pages from Arch Linux packages. Used for  [[Template:man|man page links]] from the wiki.
* [https://man.archlinux.org Arch manual pages]—contains man pages from Arch Linux packages. Used for [[Template:man|man page links]] from the wiki. You can also use the {{ic|!archman}} DuckDuckGo [https://duckduckgo.com/bang bang] to search through the Arch manual pages directly.
* [https://manned.org/ manned.org]—collection from various Linux distributions, BSD, etc., with multiple package versions
* [https://man7.org/linux/man-pages/index.html man7.org]—The Linux man-pages project. Upstream of the {{pkg|man-pages}} package. The online pages currently show an outdated version of man-pages ([https://man7.org/linux/man-pages/changelog.html 5.13], released in 2021).
* [https://manned.org/ manned.org]—collection from various Linux distributions, BSD, etc., with multiple package versions.
* [https://linux.die.net/man/ linux.die.net]
* [https://linux.die.net/man/ linux.die.net]
* [https://man.cx/ man.cx]
* [https://man.cx/ man.cx]—Man pages extracted from Debian testing.
* [https://manpages.debian.org/ Debian man pages]
* [https://manpages.debian.org/ Debian man pages]
* [http://manpages.ubuntu.com/ Ubuntu man pages]
* [https://manpages.ubuntu.com/ Ubuntu man pages]
* [https://leaf.dragonflybsd.org/cgi/web-man DragonFlyBSD man pages]
* [https://leaf.dragonflybsd.org/cgi/web-man DragonFlyBSD man pages]
* [https://www.freebsd.org/cgi/man.cgi FreeBSD man pages]
* [https://www.freebsd.org/cgi/man.cgi FreeBSD man pages]
* [http://netbsd.gw.com/cgi-bin/man-cgi NetBSD man pages]
* [https://man.netbsd.org/ NetBSD man pages]
* [https://man.openbsd.org OpenBSD man pages]
* [https://man.openbsd.org OpenBSD man pages]
* [http://man.cat-v.org/plan_9/ Plan 9 Manual — Volume 1]
* [http://man.cat-v.org/plan_9/ Plan 9 Manual — Volume 1]
Line 151: Line 184:
* [https://www.unix.com/man-page-repository.php The UNIX and Linux forums man page repository]
* [https://www.unix.com/man-page-repository.php The UNIX and Linux forums man page 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.}}
Note that while {{pkg|man-pages}} provides man pages for POSIX.1 (see [https://gitlab.archlinux.org/archlinux/packaging/packages/man-pages/-/blob/main/PKGBUILD#L13-14]), an official online reference also exists:
 
* [https://pubs.opengroup.org/onlinepubs/9699919799/ POSIX.1-2017]
 
There is also a [https://gist.github.com/rixx/6cb5fa38f694009ad0bd50c275bb61f2 comparison table] of the online databases.
 
{{Warning|Some distributions provide patched or outdated man pages that differ from those provided by Arch. Exercise caution when using online man pages.}}
{{Warning|Some distributions provide patched or outdated man pages that differ from those provided by Arch. Exercise caution when using online man pages.}}


==Noteworthy man pages==
{{Tip|The online Arch manual pages can be rendered in the terminal using this command:
{{ic|curl -sL <nowiki>'https://man.archlinux.org/man/clang.raw' | man -l -</nowiki>}}}}
 
== Noteworthy man pages ==


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).
Line 164: Line 205:
* {{man|7|credentials}}
* {{man|7|credentials}}
* {{man|5|fstab}}
* {{man|5|fstab}}
* {{man|7|hier}}
* {{man|7|file-hierarchy}}
* {{man|1|systemd}}
* {{man|1|systemd}}
* {{man|1p|locale}}, {{man|5|locale}}, {{man|7|locale}}
* {{man|1p|locale}}, {{man|5|locale}}, {{man|7|locale}}
Line 176: Line 217:
* {{man|7|utf-8}}
* {{man|7|utf-8}}


More generally, have a look at [http://man7.org/linux/man-pages/dir_section_7.html category 7 (miscellaneous) pages]:
More generally, have a look at [https://man7.org/linux/man-pages/dir_section_7.html category 7 (miscellaneous) pages]:


  $ man -s 7 -k ".*"  
  $ man -s 7 -k ".*"  
Line 183: Line 224:


* {{man|5|alpm-hooks}}
* {{man|5|alpm-hooks}}
* {{man|7|archlinux}}
* {{man|3|libalpm}}
* {{man|3|libalpm}}
* {{man|8|makepkg}}
* {{man|8|makepkg}}
Line 193: Line 233:
* {{man|8|pacman-conf}}
* {{man|8|pacman-conf}}
* {{man|8|pacman-key}}
* {{man|8|pacman-key}}
{{Expansion|Add a section on writing man pages, including conversion tools like {{Pkg|pandoc-cli}}, {{Pkg|ruby-ronn-ng}}, {{Pkg|asciidoc}}, {{Pkg|help2man}}, {{Pkg|go-md2man}}, {{Pkg|txt2man}}, {{Pkg|scdoc}}, {{aur|info2man}}, {{aur|pod2man}}, {{aur|ruby-md2man}}, etc.}}


== See also ==
== See also ==


* [https://wiki.gentoo.org/wiki/Man_page man page - Gentoo wiki article]
* [[Gentoo:man page]]
* [https://linuxtidbits.wordpress.com/2013/08/21/wtfm-write-the-fine-manual-with-pod2man-text-converter/ Write The Fine Manual with pod2man]
* [https://linuxtidbits.wordpress.com/2013/08/21/wtfm-write-the-fine-manual-with-pod2man-text-converter/ Write The Fine Manual with pod2man]
* [https://manpages.bsd.lv/history.html History of UNIX Manpages]

Latest revision as of 20:00, 9 October 2023

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.

Installation

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

man-pages provides both the Linux and the POSIX.1 man pages [1].

Some localized man pages are also available:

You can also search for all of the available localized man pages on the official repositories and on the AUR.

You can use some applications to view man pages:

  • GNOME Help — Help viewer for GNOME. Part of gnome. It can show man pages via yelp man:<name> or the undocumented Ctrl+L keybinding from an existing window.
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
  • neovim — The editor can be used to read man pages using the built-in :Man name command, or configured as a man pager with export MANPAGER='nvim +Man!'. Supports highlighting and navigation between command-line flags, keywords, and other man pages. Automatically generates an outline using section headers, command-line flags, and keywords as entries (available via gO).
https://neovim.io/ || neovim
  • Emacs — The extensible and self-documenting editor can also be used to read man pages with the built-in M-x man command.
https://www.gnu.org/software/emacs/ || emacs

Accessing man pages

To read a man page, simply enter:

$ man page_name

Manuals are sorted into several sections. Each section has an intro, such as intro(1), intro(2) and so on. For a full listing see man-pages(7) § Sections of the manual 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(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.

Or equivalently, the man page followed by the section number, separated by a period:

$ man passwd.5

Searching manuals

Man pages can be searched when the exact name of a page is not known using any of the following equivalent commands:

$ man -k expression
$ man --apropos expression
$ apropos expression

expression is interpreted as a regular expression by default.

To search for keywords in whole page texts, use the -K option instead.

Note: The search feature is provided by a dedicated cache. By default, maintenance of that cache is handled by man-db.service which gets periodically triggered by man-db.timer. If you are getting a "nothing appropriate" message for every search, try manually regenerating the cache by running mandb as root.

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

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:

Conversion to HTML

mandoc

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

$ mandoc -Thtml -Ostyle=style.css /usr/share/man/man1/free.1.gz > 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 man-db implementation 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.

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(1), which is fundamentally a typesetting language. Therefore, you can easily convert man pages to any of the formats supported as output devices by groff, which is used by man-db. For a list of output devices, see the -T option in groff(1) (or mandoc(1) if you use the mandoc package).

This will produce a PDF file:

$ man -Tpdf manpage > filename

Caveats: Fonts are generally limited to Times at hardcoded sizes. Some man pages were specifically designed for terminal viewing, and will not look right in PS or PDF form.

Online man pages

There are several online databases of man pages, including:

Note that while man-pages provides man pages for POSIX.1 (see [2]), an official online reference also exists:

There is also a comparison table of the online databases.

Warning: Some distributions provide patched or outdated man pages that differ from those provided by Arch. Exercise caution when using online man pages.
Tip: The online Arch manual pages can be rendered in the terminal using this command: curl -sL 'https://man.archlinux.org/man/clang.raw' | man -l -

Noteworthy man pages

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:

This article or section needs expansion.

Reason: Add a section on writing man pages, including conversion tools like pandoc-cli, ruby-ronn-ng, asciidoc, help2man, go-md2man, txt2man, scdoc, info2manAUR, pod2manAUR, ruby-md2manAUR, etc. (Discuss in Talk:Man page)

See also