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