Search notes:

man page

The man pages are located in /usr/share/man.
Man pages are the historical and well known way way on Unix for documentation. In a shell, a man page is accessed through the man command.
Some conventions for writing man pages are found using 
$ man 7 man-pages

Sections

1 Commands that can be executed in a shell
2 sys calls
3 libc functions except wrappers for sys calls.
4 Files found in /dev
5 File formats and configuration files
6 Games
7 Overview, conventions and miscellaneous
8 System management commands which can only be executed by root (such as mount).

Finding all man pages

apropos ., man -k ., whatis -r .

Structures of man pages

Usually, man pages have a variation of the following section headers:
Compare with the Recommended order of sections in a Perl POD (Plain Old Documentation file.
In a groff input file, section headers are created with the .SH directive.
An simple nroff file with the structure: 
.\"      Setting the title
.\"      =================
.\"
.\"      The first command in a man page should set the man page's title
.\"      with the .TH macro.
.\"
.\"      .TH takes between 2 and 5 arguments:
.\"         - title of the man page (usually written in uppercase letters)
.\"         - the man page section number
.\"         - the date of the last non trivial change of the man page  (YYYY-MM-DD)
.\"         - the source of the command (for example »GNU« or »Linux«)
.\"         - the title of the manual (for example »Linux Programmer's Manual«)
.\"
.TH  "Man page structure" 1 "2018-11-20" tq84 "about man pages"
.\"
.\"      Sections
.\"      ========
.\"
.\"      A man page is structured into sections (macro .SH) and
.\"      sub-sections (macro .SS).
.\"
.\"      The section NAME is mandatory.
.\"      At least SYNOPSIS, DESCRIPTION and SEE ALSO should at least be used.
.\"      Others, such as OPTIONS, FILES, NOTES, BUGS etc. are
.\"      additionally suggested.
.\"
.SH NAME
.\" ====
man-page-structure \- Name is the only required section and it needs a backslash followed by a hyphen.

.SH SYNOPSIS
.\" ========
This section contains a brief summary.

.SH DESCRIPTION
.\" ===========
This section explains what the thing described in the man-page actually does.

.SH SEE ALSO
.\" ========
.BR man (7),
.BR man-pages (7)

.\" vim: ft=nroff
Github repository about-man-pages, path: /examples/structure

Comments and new lines

In a roff source, a comment is introduced with \". However, this won't remove the new line which will cause a new paragraph in the output.
Therefore, comments that span an entire line and need to be completely removed while parsing, a comment usually is introduced with a leading dot: .\" which is interpreted as an undefined request.
Consider: 
line one
\" This comment is removed, BUT the new line is not.
line two

line three
.\" The dot is interpreted as undefined request and the entire line is removed.
line four

.\" vim: ft=nroff
Github repository about-man-pages, path: /examples/comments-and-new-lines
If run through man, it produces: 
line one

line two

line three line four

Viewing man pages with VIM

The value of the environment variable MANPAGER (or PAGER) specifies the program to run when man is invoked.
This, it is possible, for example, to view man pages with vim: 
$ export MANPAGER="sh -c \"col -b | vim -c 'set ft=man ts=8 nomod nolist nonu' -c 'nnoremap i <nop>' -\""
$ man …

See also

/var/cache/man
whereis (part of util-linux).

Links

roffit is a Perl script (by Daniel Stenberg) to convert (nroff?) man pages to HTML.
man-db implements the standard Unix documentation system accessed using the man command for several popular Linux distributions. It uses a Berkeley DB database in place of the traditional flat-text whatis databases.

Index