-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathmanx.1
293 lines (271 loc) · 10.7 KB
/
manx.1
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
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
.\" Man page for manx
.\"
.\" Copyright (c) 2015,2024 Jason Jackson
.\"
.\" This program is free software; you can redistribute it and/or modify it under the terms
.\" of the GNU General Public License as published by the Free Software Foundation;
.\" either version 2 of the License, or (at your option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
.\" without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
.\" See the GNU General Public License (GPLv2.txt) for more details.
.\"
.\" A copy of the GNU General Public License should accompany this program; if not,
.\" see http://www.gnu.org/licenses/gpl-2.0.html or write to the Free Software Foundation,
.\" 59 Temple Place, Suite 330, Boston, MA 02111.
.\" More details can be found at http://www.gnu.org/licenses/licenses.html.
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
. if \nF \{
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "manx 1"
.TH MANX 1 "January 2024" "macOS" "General Commands Manual"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.\" --------------------
.SH "NAME"
Manx \- view man pages in various ways on macOS
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.B manx \fR[\fIview-mode option\fR] [\fIconfiguration options ...\fR] [\fIsection\fR] \fIman-page\fR
.br
.B manx \-\-clear\-cache
.br
.B manx \-\-completion
.br
.B manx \-\-help
.\" Indent (commented out)
.\" .RS 4
View-mode options are mutually exclusive. If you pass more than one of them, the last one wins:
* \fB\-d\fR, \fB\-\-direct\fR (default if no view-mode option is passed)
* \fB\-h\fR, \fB\-\-html\fR, \fB\-\-browser\fR, \fB\-\-browser=\fR\fIAppName\fR
* \fB\-p\fR, \fB\-\-pdf\fR, \fB\-\-pdf\-viewer=\fR\fIAppName\fR
* \fB\-t\fR, \fB\-\-text\fR, \fB\-\-editor\fR, \fB\-\-editor=\fR\fIAppName\fR
* \fB\-x\fR, \fB\-\-x\-man\-page\fR
Configuration options can be combined with each other and any view mode:
* \fB\-M\fR \fImanpath\fR, \fB\-\-manpath=\fR\fImanpath\fR
* \fB\-S\fR \fIsections\fR, \fB\-\-sections=\fR\fIsections\fR
* \fB\-\-clear\-cache\fR
.\" End indent (commented out)
.\" .RE
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Manx is a command\-line utility that makes it easy to view man pages more conveniently on macOS.
By default, it presents man pages in your terminal, just like \&\fBman\fR,
but applies color and other formatting tweaks to them, to improve readability.
It also makes it easy to view man pages as HTML in your browser, PDF in Preview (or other PDF viewers),
or plain text in an editor, or to open them in macOS's built\-in man page viewer (i.e. a special Terminal window).
Manx only relies on software included with macOS to work, so it has no dependencies,
nothing else to install or configure, etc. It's just a script you can copy to wherever you'd like.
.SH "VIEW-MODE OPTIONS"
.IX Header "VIEW-MODE OPTIONS"
These options control which viewer man pages will be presented in, and/or which file type will be used.
View\-mode options are mutually exclusive. If you pass more than one of them, the last one wins.
If you don't pass any of them, the default \fB\-\-direct\fR view mode is used.
.\" --------------------
.IP "\fB\-d\fR, \fB\-\-direct\fR" 5
.IX Item "-d"
Open the man page directly in your terminal window like usual,
but with fancy colors to make it easier and more enjoyable to read.
This is the default view mode.
.\" --------------------
.IP "\fB\-h\fR, \fB\-\-html\fR, \fB\-\-browser\fR, \fB\-\-browser=\fR\fIAppName\fR" 5
.IX Item "-h"
Format the man page as HTML, and open it in your default browser
(or whichever app you have configured to open HTML files by default),
or the app you pass with the \fB\-\-browser\fR option.
.\" --------------------
.IP "\fB\-p\fR, \fB\-\-pdf\fR, \fB\-\-pdf\-viewer=\fR\fIAppName\fR" 5
.IX Item "-p"
Format the man page as PDF, and open it in your default PDF viewer,
or the app you pass with the \fB\-\-pdf\-viewer\fR option.
.\" --------------------
.IP "\fB\-t\fR, \fB\-\-text\fR, \fB\-\-editor\fR, \fB\-\-editor=\fR\fIAppName\fR" 5
.IX Item "-t"
Format the man page as plain text, and open it in your default editor,
or the app you pass with the \fB\-\-editor\fR option.
.\" --------------------
.IP "\fB\-x\fR, \fB\-\-x\-man\-page\fR" 5
.IX Item "-x"
Open the man page using macOS's x\-man\-page URL scheme,
i.e. in a Terminal window with special formatting and colors.
.SH "CONFIGURATION OPTIONS"
.IX Header "CONFIGURATION OPTIONS"
These options can be combined with each other, and used in any view mode.
.\" --------------------
.IP "\fB\-M\fR \fImanpath\fR, \fB\-\-manpath=\fR\fImanpath\fR" 5
.IX Item "-M"
A colon-separated list of directories to search for man pages, instead of the default.
Works just like “\fBman -M\fR”. Overrides the \fBMANPATH\fR environment variable. Also see manpath(1).
.\" --------------------
.IP "\fB\-S\fR \fIsections\fR, \fB\-\-sections=\fR\fIsections\fR" 5
.IX Item "-S"
A manual section, or colon-separated list of sections, to search instead of the default.
Works just like “\fBman -S\fR”. Overrides the \fBMANSECT\fR environment variable.
.\" --------------------
.IP "\fB\-\-clear\-cache\fR" 5
.IX Item "--clear-cache"
Remove cached generated HTML/PDF/text files, from previous invocations of \fBmanx\fR.
You may use this option with or without viewing a man page.
.SH "SPECIAL OPTIONS"
.IX Header "SPECIAL OPTIONS"
These options make Manx do something other than view a man page.
.\" --------------------
.IP "\fB\-\-completion\fR" 5
.IX Item "--completion"
Output shell script that implements command\-line completion for Manx in zsh, then exit.
If you already have zsh's completion system set up, and you're running “compinit” in your ~/.zshrc file,
running a command along these lines should be all that's needed to begin using Manx's completions:
manx \-\-completion > "$fpath[1]/_manx" && rm \-f ~/.zcompdump
Zsh's completion system is documented in full here:
.br
https://zsh.sourceforge.io/Doc/Release/Completion-System.html
.\" --------------------
.IP "\fB\-\-help\fR" 5
.IX Item "--help"
Display usage information and immediately exit.
.SH "ENVIRONMENT"
.IX Header "ENVIRONMENT"
If the \fBMANX_OPTIONS\fR environment variable is set, options are parsed from it before command\-line options are parsed.
This allows you to set defaults, such as your preferred viewer, and later override those choices on the command line if desired.
For instance, you could set \fBMANX_OPTIONS\fR to “\-\-pdf” to view man pages as PDF by default,
using just “\fBmanx\fR \fIman\-page\fR” on the command line, but later choose to view a specific man page in a different viewer
by using a command\-line option in the usual way.
Setting the \fBMANPATH\fR environment variable changes the search path to the specified list of directories, separated by colons.
Absolute paths must be used. Invalid paths, and paths without manual databases, are ignored.
Setting the \fBMANSECT\fR environment variable restricts manual sections searched to the specified colon delimited list,
just like the \fB-S\fR option. All sections are searched by default.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
man(1), mandoc(1), manpath(1)