Annotation of mandoc/man.1, Revision 1.8
1.8 ! schwarze 1: .\" $Id: man.1,v 1.7 2014/11/11 02:43:41 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>
6: .\" Copyright (c) 2010, 2011 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.8 ! schwarze 34: .Dd $Mdocdate: November 11 2014 $
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.4 schwarze 42: .Op Fl acfhklVw
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
! 109: macro.
1.1 schwarze 110: .It Fl h
1.5 schwarze 111: Display only the SYNOPSIS lines of the requested manual pages.
112: Implies
1.7 schwarze 113: .Fl a
114: and
115: .Fl c .
1.8 ! schwarze 116: .It Fl K Ar encoding
! 117: Specify the input encoding.
! 118: The supported
! 119: .Ar encoding
! 120: arguments are
! 121: .Cm us-ascii ,
! 122: .Cm iso-8859-1 ,
! 123: and
! 124: .Cm utf-8 .
! 125: By default, the encoding is automatically detected as described in the
! 126: .Xr mandoc 1
! 127: manual.
1.2 schwarze 128: .It Fl k
1.1 schwarze 129: A synonym for
130: .Xr apropos 1 .
1.2 schwarze 131: Instead of
132: .Ar name ,
133: an expression can be provided using the syntax described in the
134: .Xr apropos 1
135: manual.
136: By default, it displays the header lines of all matching pages.
1.4 schwarze 137: This overrides any earlier
138: .Fl f
139: and
140: .Fl l
141: options.
142: .It Fl l
143: A synonym for
144: .Xr mandoc 1
145: .Fl a .
146: The
147: .Ar name
148: arguments are interpreted as filenames.
149: No search is done and
150: .Ar file ,
151: .Ar path ,
152: .Ar section ,
153: and
154: .Ar subsection
155: are ignored.
156: This overrides any earlier
157: .Fl f ,
158: .Fl k ,
159: and
160: .Fl w
161: options.
1.1 schwarze 162: .It Fl M Ar path
163: Override the list of standard directories which
164: .Nm
165: searches for manual pages.
166: The supplied
167: .Ar path
168: must be a colon
169: .Pq Ql \&:
170: separated list of directories.
171: This search path may also be set using the environment variable
172: .Ev MANPATH .
173: The subdirectories to be searched, and their search order,
174: are specified by the
175: .Dq _subdir
176: line in the
177: .Nm
178: configuration file.
179: .It Fl m Ar path
180: Augment the list of standard directories which
181: .Nm
182: searches for manual pages.
183: The supplied
184: .Ar path
185: must be a colon
186: .Pq Ql \&:
187: separated list of directories.
188: These directories will be searched before the standard directories or
189: the directories specified using the
190: .Fl M
191: option or the
192: .Ev MANPATH
193: environment variable.
194: The subdirectories to be searched, and their search order,
195: are specified by the
196: .Dq _subdir
197: line in the
198: .Nm
199: configuration file.
1.8 ! schwarze 200: .It Fl O Ar option Ns = Ns Ar value
! 201: Comma-separated output options.
! 202: For each output format, the available options are described in the
! 203: .Xr mandoc 1
! 204: manual.
1.1 schwarze 205: .It Fl S Ar subsection
206: Restricts the directories that
207: .Nm
208: will search to those of a specific
209: .Xr machine 1
210: architecture.
211: .Ar subsection
212: is case insensitive.
213: .Pp
214: By default manual pages for all architectures are installed.
215: Therefore this option can be used to view pages for one
216: architecture whilst using another.
217: .Pp
218: This option overrides the
219: .Ev MACHINE
220: environment variable.
221: .It Xo
222: .Op Fl s
223: .Ar section
224: .Xc
225: Restricts the directories that
226: .Nm
227: will search to a specific section.
228: The currently available sections are:
229: .Pp
230: .Bl -tag -width "localXXX" -offset indent -compact
231: .It 1
232: General commands
233: .Pq tools and utilities .
234: .It 2
235: System calls and error numbers.
236: .It 3
237: Libraries.
238: .It 3f
239: Fortran programmer's reference guide.
240: .It 3p
241: .Xr perl 1
242: programmer's reference guide.
243: .It 4
244: Device drivers.
245: .It 5
246: File formats.
247: .It 6
248: Games.
249: .It 7
250: Miscellaneous.
251: .It 8
252: System maintenance and operation commands.
253: .It 9
254: Kernel internals.
255: .It X11
256: An alias for X11R6.
257: .It X11R6
258: X Window System.
259: .It local
260: Pages located in
261: .Pa /usr/local .
262: .It n
263: Tcl/Tk commands.
264: .El
265: .Pp
266: The
267: .Nm
268: configuration file,
269: .Xr man.conf 5 ,
270: specifies the possible
271: .Ar section
272: values, and their search order.
273: Additional sections may be specified.
1.8 ! schwarze 274: .It Fl T Ar output
! 275: Select the output format.
! 276: The default is
! 277: .Cm locale .
! 278: The other output modes
! 279: .Cm ascii ,
! 280: .Cm html ,
! 281: .Cm lint ,
! 282: .Cm man ,
! 283: .Cm pdf ,
! 284: .Cm ps ,
! 285: .Cm tree ,
! 286: and
! 287: .Cm utf8
! 288: are described in the
! 289: .Xr mandoc 1
! 290: manual.
1.4 schwarze 291: .It Fl V
292: Print version and exit.
1.8 ! schwarze 293: .It Fl W Ar level
! 294: Specify the minimum message
! 295: .Ar level
! 296: to be reported on the standard error output and to affect the exit status.
! 297: The
! 298: .Ar level
! 299: can be
! 300: .Cm warning ,
! 301: .Cm error ,
! 302: or
! 303: .Cm fatal .
! 304: The default is
! 305: .Cm fatal ;
! 306: .Cm all
! 307: is an alias for
! 308: .Cm warning .
! 309: See the
! 310: .Xr mandoc 1
! 311: manual for details.
1.1 schwarze 312: .It Fl w
313: List the pathnames of the manual pages which
314: .Nm
315: would display for the specified
316: .Ar section
317: and
318: .Ar name
319: combination.
320: .El
321: .Pp
1.2 schwarze 322: Guidelines for writing
1.1 schwarze 323: man pages can be found in
324: .Xr mdoc 7 .
325: .Pp
326: If both a formatted and an unformatted version of the same manual page,
327: for example
328: .Pa cat1/foo.0
329: and
330: .Pa man1/foo.1 ,
331: exist in the same directory, and at least one of them is selected,
332: only the newer one is used.
333: However, if both the
334: .Fl a
335: and the
336: .Fl w
337: options are specified, both file names are printed.
338: .Sh ENVIRONMENT
339: .Bl -tag -width MANPATHX
340: .It Ev MACHINE
341: As some manual pages are intended only for specific architectures,
342: .Nm
343: searches any subdirectories,
344: with the same name as the current architecture,
345: in every directory which it searches.
346: Machine specific areas are checked before general areas.
347: The current machine type may be overridden by setting the environment
348: variable
349: .Ev MACHINE
350: to the name of a specific architecture,
351: or with the
352: .Fl S
353: option.
354: .Ev MACHINE
355: is case insensitive.
356: .It Ev MANPAGER
357: Any non-empty value of the environment variable
358: .Ev MANPAGER
359: will be used instead of the standard pagination program,
360: .Xr more 1 .
361: .It Ev MANPATH
362: The standard search path used by
363: .Nm
364: may be overridden by specifying a path in the
365: .Ev MANPATH
366: environment
367: variable.
368: The format of the path is a colon
369: .Pq Ql \&:
370: separated list of directories.
371: The subdirectories to be searched, as well as their search order,
372: are specified by the
373: .Dq _subdir
374: line in the
375: .Nm
376: configuration file.
377: .It Ev PAGER
378: Specifies the pagination program to use when
379: .Ev MANPAGER
380: is not defined.
381: If neither PAGER nor MANPAGER is defined,
382: .Pa /usr/bin/more Fl s
383: will be used.
384: .El
385: .Sh FILES
386: .Bl -tag -width /etc/man.conf -compact
387: .It Pa /etc/man.conf
388: default man configuration file
389: .El
390: .Sh EXIT STATUS
391: .Ex -std man
392: .Sh SEE ALSO
393: .Xr apropos 1 ,
394: .Xr intro 1 ,
395: .Xr whatis 1 ,
396: .Xr whereis 1 ,
397: .Xr intro 2 ,
398: .Xr intro 3 ,
399: .Xr intro 4 ,
400: .Xr intro 5 ,
401: .Xr man.conf 5 ,
402: .Xr intro 6 ,
403: .Xr intro 7 ,
404: .Xr mdoc 7 ,
405: .Xr intro 8 ,
406: .Xr intro 9
407: .Sh STANDARDS
408: The
409: .Nm
410: utility is compliant with the
411: .St -p1003.1-2008
412: specification.
413: .Pp
414: The flags
415: .Op Fl aCcfhMmSsw ,
416: as well as the environment variables
417: .Ev MACHINE ,
418: .Ev MANPAGER ,
419: and
420: .Ev MANPATH ,
421: are extensions to that specification.
422: .Sh HISTORY
423: A
424: .Nm
425: command first appeared in
426: .At v3 .
427: .Pp
428: The
429: .Fl w
430: option first appeared in
431: .At v7 ;
432: .Fl f
433: and
434: .Fl k
435: in
436: .Bx 4 ;
437: .Fl M
438: in
439: .Bx 4.3 ;
440: .Fl a
441: in
442: .Bx 4.3 Tahoe ;
443: .Fl c
444: and
445: .Fl m
446: in
447: .Bx 4.3 Reno ;
448: .Fl h
449: in
450: .Bx 4.3 Net/2 ;
451: .Fl C
452: in
453: .Nx 1.0 ;
454: and
455: .Fl s
456: and
457: .Fl S
458: in
459: .Ox 2.3 .
CVSweb