.Dd $Mdocdate$
.Dt NMAN 1
.Os
.Sh NAME
.Nm nman
.Nd nix-shell for man pages
.Sh SYNOPSIS
.Nm
.Op Fl h
.Ar ATTR
.Op Ar PAGE | SECTION Op PAGE
.Sh DESCRIPTION
.Nm
is a simple tool allowing to open man pages of packages
which are not installed using the power of the
.Xr nix 1
package manager.
It allows you to specify a package and a man
page and opens it directly using
.Xr man 1 ,
essentially implementing what you would expect
.Ql nix-shell -p foo --run 'man foo'
to do, but
.Nm
will only download the minimum amount of data necessary to read the man page.
.Pp
You can invoke
.Nm
in four different ways:
.Bl -ohang -offset 2n
.It Nm Ar ATTR
Evaluates the attribute
.Ar ATTR
of
.Ql <nixpkgs>
and searches all its outputs for a man page named
.Ar ATTR
which may be in any section.
If multiple matches are found, the one that is alphanumerically
lower is preferred:
For example,
.Xr lowdown 1
is preferred over
.Xr lowdown 3 .
.It Nm Ar ATTR SECTION
Like above, but
.Nm
will only look for the man page in the given section
.Ar SECTION .
Note that
.Ar SECTION
must be a number or
.Ql 3p ,
otherwise the next invocation is assumed.
.It Nm Ar ATTR PAGE
Opens the man page
.Ar PAGE
from package
.Ar ATTR .
Man section precedence works like described above.
.It Nm Ar ATTR SECTION PAGE
Opens man page
.Ar PAGE
in section
.Ar SECTION
from the package described by
.Ar ATTR .
This is the invocation with the least magic and works
just like invoking
.Xr man 1
with two arguments.
.El
.Sh EXAMPLES
.Bd -literal
# 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
.Ed
.Sh DISCLAIMER
.Nm
is intended to be used interactively:
It automatically launches a pager and relies heavily on heuristics
to automatically
.Dq 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.
.Pp
Therefore neither the behavior nor the user interface of
.Nm
should be considered stable or used for scripting purposes.
.Sh IMPLEMENTATION NOTES
.Nm
uses
.Xr nix-instantiate 1
to first evaluate all the derivation outputs of the given attribute.
It then utilizes
.Xr 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
.Xr man 1 .
.Pp
The outputs are checked in order of likelihood to contain man pages.
This means that
.Nm
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
.Ql man ,
.Ql devman
or
.Ql out .
.Pp
.Nm
also creates temporary gc-roots for the derivations and outputs
to prevent any race conditions with the nix garbage collector.
.Sh ENVIRONMENT
.Nm
uses
.Ev PATH
to find its dependencies:
.Xr man 1 ,
.Xr nix-instantiate 1
and
.Xr nix-store 1
have to be in
.Ev PATH
for it to run.
.Pp
You can also influence the behavior of the
.Xr nix-instantiate 1
and
.Xr nix-store 1
child processes using environment variables.
For a complete list of them refer to their respective documentation.
.Pp
Most useful is probably
.Ev NIX_PATH
which allows you to change the
.Ql <nixpkgs>
.Nm
uses for building the desired package:
.Pp
.D1 env NIX_PATH="nixpkgs=$HOME/nixpkgs" nman coreutils-full ln
.Pp
opens the
.Xr ln 1
man page for the
.Ql coreutils-full
package from a local checkout of nixpkgs.
.Pp
Depending on the implementation of
.Xr man 1 ,
.Ev MANPAGER
and
.Ev PAGER
can be used to determine the program used for displaying man pages.
.Sh EXIT STATUS
.Bl -tag -width Ds
.It 0
Success.
.It 1
An expected error like a man page not being found or the requested
package not existing.
.It 100
An usage error, indicating the user is invoking
.Nm
wrong.
.It 101
An unexpected error like a build failing, other utilities producing
garbage output or I/O errors.
.It 127
A dependency is missing or not found in
.Ev PATH .
.El
.Sh SEE ALSO
.Xr nix-instantiate 1 ,
.Xr nix-store 1 and
.Xr man 1 .
.Sh AUTHORS
.Nm
was written by
.An Profpatsch ,
.Mt mail@profpatsch.de ,
and
.An sternenseemann ,
.Mt sternenseemann@systemli.org .