NAME

nman - nix-shell for man pages

SYNOPSIS

nman [-hv] ATTR [PAGE | SECTION [PAGE]]

DESCRIPTION

nman is a simple tool allowing to open man pages of packages which are not installed using the power of the nix(1) package manager. It allows you to specify a package and a man page and opens it directly using man(1), essentially implementing what you would expect 'nix-shell -p foo --run 'man foo'' to do, but nman will only download the minimum amount of data necessary to read the man page.

You can invoke nman in four different ways:

nman ATTR
Evaluates the attribute ATTR of '<nixpkgs>' and searches all its outputs for a man page named ATTR which may be in any section. If multiple matches are found, the one that is alphanumerically lower is preferred: For example, lowdown(1) is preferred over lowdown(3).

nman ATTR SECTION
Like above, but nman will only look for the man page in the given section SECTION. Note that SECTION must be a number or '3p', otherwise the next invocation is assumed.

nman ATTR PAGE
Opens the man page PAGE from package ATTR. Man section precedence works like described above.

nman ATTR SECTION PAGE
Opens man page PAGE in section SECTION from the package described by ATTR. This is the invocation with the least magic and works just like invoking man(1) with two arguments.

The following options modify the behavior of nman:

--help | --usage | -h

Print usage information.

--verbose | -v

Put
**nman**
into verbose mode, where it prints all commands it executes.

EXAMPLES

# open lowdown(1)
nman lowdown
# open lowdown(3) from the same package
nman lowdown 3

# open lowdown_html_rndr(3)
nman lowdown lowdown_html_rndr

# open man(1) from the mandoc package
nman mandoc man

# open man(7) from the same package
nman mandoc 7 man

DISCLAIMER

nman is intended to be used interactively: It automatically launches a pager and relies heavily on heuristics to automatically "do the right thing" without the user having to think about it. The nature of such heuristics however dictates that they are often imperfect and require tweaking.

Therefore neither the behavior nor the user interface of nman should be considered stable or used for scripting purposes.

IMPLEMENTATION NOTES

nman uses nix-instantiate(1) to first evaluate all the derivation outputs of the given attribute. It then utilizes nix-store(1) to realise (that is to download or build) the outputs one by one until it finds the desired man page or runs out of outputs. When the man page is found, it is opened using man(1).

The outputs are checked in order of likelihood to contain man pages. This means that nman is as fast as possible and downloads the least amount of data possible for packages that follow good conventions, like having their man pages in 'man', 'devman' or 'out'.

nman also creates temporary gc-roots for the derivations and outputs to prevent any race conditions with the nix garbage collector.

ENVIRONMENT

nman uses PATH to find its dependencies: man(1), nix-instantiate(1) and nix-store(1) have to be in PATH for it to run.

You can also influence the behavior of the nix-instantiate(1) and nix-store(1) child processes using environment variables. For a complete list of them refer to their respective documentation.

Most useful is probably NIX_PATH which allows you to change the '<nixpkgs>' nman uses for building the desired package:

env NIX_PATH="nixpkgs=$HOME/nixpkgs" nman coreutils-full ln

opens the ln(1) man page for the 'coreutils-full' package from a local checkout of nixpkgs.

Depending on the implementation of man(1), MANPAGER and PAGER can be used to determine the program used for displaying man pages.

EXIT STATUS

0

Success.

1

An expected error like a man page not being found or the requested
package not existing.

100

An usage error, indicating the user is invoking
**nman**
wrong.

101

An unexpected error like a build failing, other utilities producing
garbage output or I/O errors.

127

A dependency is missing or not found in
`PATH`.

SEE ALSO

nix-instantiate(1), nix-store(1) and man(1).

AUTHORS

nman was written by Profpatsch <mail@profpatsch.de> and
sternenseemann <sternenseemann@systemli.org>.