1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
|
.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 .
|
