.. -*- coding: utf-8; -*-
.. include:: HEADER.rst

===========
 Man pages
===========
.. contents::
   :local:

Man sections
============

  1 Executable programs or shell commands.
  2 System calls (functions provided by the kernel).
  3 Library calls (functions within program libraries).
  4 Special files (usually found in /dev).
  5 File formats and conventions eg /etc/passwd.
  6 Games.
  7 Miscellaneous (including macro  packages  and  conventions).
  8 System administration commands (usually only for root).

Invoking man
============

Search for prog, func, conf file::

  $ man [<section>] <item>

Search by specific keywords::

  $ man -k <keywords>

Viewing inside Emacs::

  M-x man RET [<section>] <item>
  M-x man RET -k SPACE <keywords>

Sections order
==============
::

  NAME                - brief prog description
  SYNOPSIS (USAGE)    - command line options in BNF
  DESCRIPTION         - long prog description
  OPTIONS             - long option descriptions
  ... misc sections ...
  EXAMPLES
  EXIT STATUS
  ENVIRONMENT
  AVAILABILITY        - whare search source, where home page
  FILES               - list of files that has effect on program working
  AUTHORS
  COPYRIGHT
  SEE ALSO
  BUGS                - know issue, how report bug
  HISTORY

Man page showing
================

TODO
Bolt by print char, back one char and print same char.
Underscore by printing undescore, back one char and print char.

Development tools
=================

To preview local man page::

  $ groff -man -Tascii foo.1            # 7-bit char
  $ groff -man -Tlatin1 foo.1           # 8-bit char
  $ groff -man -Tlatin1 foo.1 | less
  $ groff -a -mandoc -Tlatin1 e.1
  $ groff -man -Tutf8 foo.1

  $ man ./foo.1                         # if slashes in path - use file

  $ mkdir man1
  $ cp foo.1 man1
  $ man -M . 1 foo                      # without slashes search in MANPATH item
                                        # and add /man1 to each item

Output format
=============

Plain text::

  $ man foo | col -b >.foo.txt

PostScript::

  $ groff -Tps foo >foo.ps

DVI::

  $ groff -Tdvi foo >foo.dvi