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
199
200
201
202
203
204
205
206
207
208
209
210
|
.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 .
|
