.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 SECTION PAGE
Evaluates the attribute
.Ar ATTR
of
.Ql <nixpkgs>
and searches all its outputs for a man page of name
.Ar PAGE
in man section
.Ar SECTION .
.Ar PAGE
and
.Ar SECTION
work just like with
.Xr man 1 .
.It Nm Ar ATTR SECTION
Like above, but
.Ar ATTR
is also used as the name of the man page.
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 .
If multiple matches are found, pages from lower
man sections are preferred, for example
.Ql nman lowdown lowdown
opens
.Xr lowdown 1
and not
.Xr lowdown 3 .
.It Nm Ar ATTR
Uses the described method to find the man page
.Ar ATTR
from package
.Ar ATTR .
.El
.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 EXAMPLES
Open
.Xr lowdown 1 :
.Pp
.D1 nman lowdown
.Pp
Open
.Xr lowdown 3
from the same package
.Pp
.D1 nman lowdown 3
.Pp
Open
.Xr lowdown_html_rndr 3 :
.Pp
.D1 nman lowdown lowdown_html_rndr
.Pp
Open
.Xr man 1
from the
.Ql mandoc
package:
.Pp
.D1 nman mandoc man
.Pp
Now open
.Xr man 7
from the same package:
.Pp
.D1 nman mandoc 7 man
.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 .