Annotation of mandoc/man.1, Revision 1.13
1.13 ! schwarze 1: .\" $Id: man.1,v 1.12 2015/01/20 21:16:51 schwarze Exp $
1.1 schwarze 2: .\"
3: .\" Copyright (c) 1989, 1990, 1993
4: .\" The Regents of the University of California. All rights reserved.
1.2 schwarze 5: .\" Copyright (c) 2003, 2007, 2008, 2014 Jason McIntyre <jmc@openbsd.org>
1.11 schwarze 6: .\" Copyright (c) 2010, 2011, 2014, 2015 Ingo Schwarze <schwarze@openbsd.org>
1.1 schwarze 7: .\"
8: .\" Redistribution and use in source and binary forms, with or without
9: .\" modification, are permitted provided that the following conditions
10: .\" are met:
11: .\" 1. Redistributions of source code must retain the above copyright
12: .\" notice, this list of conditions and the following disclaimer.
13: .\" 2. Redistributions in binary form must reproduce the above copyright
14: .\" notice, this list of conditions and the following disclaimer in the
15: .\" documentation and/or other materials provided with the distribution.
16: .\" 3. Neither the name of the University nor the names of its contributors
17: .\" may be used to endorse or promote products derived from this software
18: .\" without specific prior written permission.
19: .\"
20: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30: .\" SUCH DAMAGE.
31: .\"
32: .\" @(#)man.1 8.2 (Berkeley) 1/2/94
33: .\"
1.13 ! schwarze 34: .Dd $Mdocdate: January 20 2015 $
1.1 schwarze 35: .Dt MAN 1
36: .Os
37: .Sh NAME
38: .Nm man
39: .Nd display manual pages
40: .Sh SYNOPSIS
41: .Nm man
1.13 ! schwarze 42: .Op Fl acfhklw
1.1 schwarze 43: .Op Fl C Ar file
1.8 schwarze 44: .Op Fl I Cm os Ns = Ns Ar name
45: .Op Fl K Ar encoding
1.1 schwarze 46: .Op Fl M Ar path
47: .Op Fl m Ar path
1.8 schwarze 48: .Op Fl O Ar option Ns = Ns Ar value
1.1 schwarze 49: .Op Fl S Ar subsection
50: .Op Fl s Ar section
1.8 schwarze 51: .Op Fl T Ar output
52: .Op Fl W Ar level
1.1 schwarze 53: .Op Ar section
54: .Ar name ...
55: .Sh DESCRIPTION
56: The
57: .Nm
58: utility
59: displays the
60: manual pages entitled
61: .Ar name .
62: Pages may be selected according to
63: a specific category
64: .Pq Ar section
65: or
66: machine architecture
67: .Pq Ar subsection .
68: .Pp
69: The options are as follows:
70: .Bl -tag -width Ds
71: .It Fl a
72: Display all of the manual pages for a specified
73: .Ar section
74: and
75: .Ar name
76: combination.
77: Normally, only the first manual page found is displayed.
78: .It Fl C Ar file
79: Use the specified
80: .Ar file
81: instead of the default configuration file.
82: This permits users to configure their own manual environment.
83: See
84: .Xr man.conf 5
85: for a description of the contents of this file.
86: .It Fl c
87: Copy the manual page to the standard output instead of using
88: .Xr more 1
89: to paginate it.
90: This is done by default if the standard output is not a terminal device.
1.2 schwarze 91: .It Fl f
1.1 schwarze 92: A synonym for
93: .Xr whatis 1 .
1.2 schwarze 94: It searches for
95: .Ar name
96: in manual page names and displays the header lines from all matching pages.
97: The search is case insensitive and matches whole words only.
1.4 schwarze 98: This overrides any earlier
99: .Fl k
100: and
101: .Fl l
102: options.
1.8 schwarze 103: .It Fl I Cm os Ns = Ns Ar name
104: Override the default operating system
105: .Ar name
106: for the
107: .Xr mdoc 7
108: .Ic \&Os
1.10 schwarze 109: and for the
110: .Xr man 7
111: .Ic \&TH
1.8 schwarze 112: macro.
1.1 schwarze 113: .It Fl h
1.5 schwarze 114: Display only the SYNOPSIS lines of the requested manual pages.
115: Implies
1.7 schwarze 116: .Fl a
117: and
118: .Fl c .
1.8 schwarze 119: .It Fl K Ar encoding
120: Specify the input encoding.
121: The supported
122: .Ar encoding
123: arguments are
124: .Cm us-ascii ,
125: .Cm iso-8859-1 ,
126: and
127: .Cm utf-8 .
128: By default, the encoding is automatically detected as described in the
129: .Xr mandoc 1
130: manual.
1.2 schwarze 131: .It Fl k
1.1 schwarze 132: A synonym for
133: .Xr apropos 1 .
1.2 schwarze 134: Instead of
135: .Ar name ,
136: an expression can be provided using the syntax described in the
137: .Xr apropos 1
138: manual.
139: By default, it displays the header lines of all matching pages.
1.4 schwarze 140: This overrides any earlier
141: .Fl f
142: and
143: .Fl l
144: options.
145: .It Fl l
146: A synonym for
147: .Xr mandoc 1
148: .Fl a .
149: The
150: .Ar name
151: arguments are interpreted as filenames.
152: No search is done and
153: .Ar file ,
154: .Ar path ,
155: .Ar section ,
156: and
157: .Ar subsection
158: are ignored.
159: This overrides any earlier
160: .Fl f ,
161: .Fl k ,
162: and
163: .Fl w
164: options.
1.1 schwarze 165: .It Fl M Ar path
166: Override the list of standard directories which
167: .Nm
168: searches for manual pages.
169: The supplied
170: .Ar path
171: must be a colon
172: .Pq Ql \&:
173: separated list of directories.
174: This search path may also be set using the environment variable
175: .Ev MANPATH .
176: The subdirectories to be searched, and their search order,
177: are specified by the
178: .Dq _subdir
179: line in the
180: .Nm
181: configuration file.
182: .It Fl m Ar path
183: Augment the list of standard directories which
184: .Nm
185: searches for manual pages.
186: The supplied
187: .Ar path
188: must be a colon
189: .Pq Ql \&:
190: separated list of directories.
191: These directories will be searched before the standard directories or
192: the directories specified using the
193: .Fl M
194: option or the
195: .Ev MANPATH
196: environment variable.
197: The subdirectories to be searched, and their search order,
198: are specified by the
199: .Dq _subdir
200: line in the
201: .Nm
202: configuration file.
1.8 schwarze 203: .It Fl O Ar option Ns = Ns Ar value
204: Comma-separated output options.
205: For each output format, the available options are described in the
206: .Xr mandoc 1
207: manual.
1.1 schwarze 208: .It Fl S Ar subsection
209: Restricts the directories that
210: .Nm
211: will search to those of a specific
212: .Xr machine 1
213: architecture.
214: .Ar subsection
215: is case insensitive.
216: .Pp
217: By default manual pages for all architectures are installed.
218: Therefore this option can be used to view pages for one
219: architecture whilst using another.
220: .Pp
221: This option overrides the
222: .Ev MACHINE
223: environment variable.
224: .It Xo
225: .Op Fl s
226: .Ar section
227: .Xc
228: Restricts the directories that
229: .Nm
230: will search to a specific section.
231: The currently available sections are:
232: .Pp
233: .Bl -tag -width "localXXX" -offset indent -compact
234: .It 1
235: General commands
236: .Pq tools and utilities .
237: .It 2
238: System calls and error numbers.
239: .It 3
240: Libraries.
241: .It 3f
242: Fortran programmer's reference guide.
243: .It 3p
244: .Xr perl 1
245: programmer's reference guide.
246: .It 4
247: Device drivers.
248: .It 5
249: File formats.
250: .It 6
251: Games.
252: .It 7
253: Miscellaneous.
254: .It 8
255: System maintenance and operation commands.
256: .It 9
257: Kernel internals.
258: .It X11
259: An alias for X11R6.
260: .It X11R6
261: X Window System.
262: .It local
263: Pages located in
264: .Pa /usr/local .
265: .It n
266: Tcl/Tk commands.
267: .El
268: .Pp
269: The
270: .Nm
271: configuration file,
272: .Xr man.conf 5 ,
273: specifies the possible
274: .Ar section
275: values, and their search order.
276: Additional sections may be specified.
1.8 schwarze 277: .It Fl T Ar output
278: Select the output format.
279: The default is
280: .Cm locale .
281: The other output modes
282: .Cm ascii ,
283: .Cm html ,
284: .Cm lint ,
285: .Cm man ,
286: .Cm pdf ,
287: .Cm ps ,
288: .Cm tree ,
289: and
290: .Cm utf8
291: are described in the
292: .Xr mandoc 1
293: manual.
294: .It Fl W Ar level
295: Specify the minimum message
296: .Ar level
297: to be reported on the standard error output and to affect the exit status.
298: The
299: .Ar level
300: can be
1.12 schwarze 301: .Cm warning ,
302: .Cm error ,
1.8 schwarze 303: or
1.12 schwarze 304: .Cm unsupp ;
1.8 schwarze 305: .Cm all
306: is an alias for
307: .Cm warning .
1.11 schwarze 308: By default,
309: .Nm
310: is silent.
1.8 schwarze 311: See the
312: .Xr mandoc 1
313: manual for details.
1.1 schwarze 314: .It Fl w
315: List the pathnames of the manual pages which
316: .Nm
317: would display for the specified
318: .Ar section
319: and
320: .Ar name
321: combination.
322: .El
323: .Pp
1.2 schwarze 324: Guidelines for writing
1.1 schwarze 325: man pages can be found in
326: .Xr mdoc 7 .
327: .Pp
328: If both a formatted and an unformatted version of the same manual page,
329: for example
330: .Pa cat1/foo.0
331: and
332: .Pa man1/foo.1 ,
333: exist in the same directory, and at least one of them is selected,
334: only the newer one is used.
335: However, if both the
336: .Fl a
337: and the
338: .Fl w
339: options are specified, both file names are printed.
340: .Sh ENVIRONMENT
341: .Bl -tag -width MANPATHX
342: .It Ev MACHINE
343: As some manual pages are intended only for specific architectures,
344: .Nm
345: searches any subdirectories,
346: with the same name as the current architecture,
347: in every directory which it searches.
348: Machine specific areas are checked before general areas.
349: The current machine type may be overridden by setting the environment
350: variable
351: .Ev MACHINE
352: to the name of a specific architecture,
353: or with the
354: .Fl S
355: option.
356: .Ev MACHINE
357: is case insensitive.
358: .It Ev MANPAGER
359: Any non-empty value of the environment variable
360: .Ev MANPAGER
361: will be used instead of the standard pagination program,
362: .Xr more 1 .
363: .It Ev MANPATH
364: The standard search path used by
365: .Nm
366: may be overridden by specifying a path in the
367: .Ev MANPATH
368: environment
369: variable.
370: The format of the path is a colon
371: .Pq Ql \&:
372: separated list of directories.
373: The subdirectories to be searched, as well as their search order,
374: are specified by the
375: .Dq _subdir
376: line in the
377: .Nm
378: configuration file.
379: .It Ev PAGER
380: Specifies the pagination program to use when
381: .Ev MANPAGER
382: is not defined.
383: If neither PAGER nor MANPAGER is defined,
384: .Pa /usr/bin/more Fl s
385: will be used.
386: .El
387: .Sh FILES
388: .Bl -tag -width /etc/man.conf -compact
389: .It Pa /etc/man.conf
390: default man configuration file
391: .El
392: .Sh EXIT STATUS
393: .Ex -std man
394: .Sh SEE ALSO
395: .Xr apropos 1 ,
396: .Xr intro 1 ,
397: .Xr whatis 1 ,
398: .Xr whereis 1 ,
399: .Xr intro 2 ,
400: .Xr intro 3 ,
401: .Xr intro 4 ,
402: .Xr intro 5 ,
403: .Xr man.conf 5 ,
404: .Xr intro 6 ,
405: .Xr intro 7 ,
406: .Xr mdoc 7 ,
407: .Xr intro 8 ,
408: .Xr intro 9
409: .Sh STANDARDS
410: The
411: .Nm
412: utility is compliant with the
413: .St -p1003.1-2008
414: specification.
415: .Pp
416: The flags
1.13 ! schwarze 417: .Op Fl aCcfhIKlMmOSsTWw ,
1.1 schwarze 418: as well as the environment variables
419: .Ev MACHINE ,
420: .Ev MANPAGER ,
421: and
422: .Ev MANPATH ,
423: are extensions to that specification.
424: .Sh HISTORY
425: A
426: .Nm
427: command first appeared in
428: .At v3 .
429: .Pp
430: The
431: .Fl w
432: option first appeared in
433: .At v7 ;
434: .Fl f
435: and
436: .Fl k
437: in
438: .Bx 4 ;
439: .Fl M
440: in
441: .Bx 4.3 ;
442: .Fl a
443: in
444: .Bx 4.3 Tahoe ;
445: .Fl c
446: and
447: .Fl m
448: in
449: .Bx 4.3 Reno ;
450: .Fl h
451: in
452: .Bx 4.3 Net/2 ;
453: .Fl C
454: in
455: .Nx 1.0 ;
456: and
457: .Fl s
458: and
459: .Fl S
460: in
461: .Ox 2.3 .
CVSweb