Annotation of mandoc/man.1, Revision 1.2
1.2 ! schwarze 1: .\" $Id$
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
223: .Pp
1.2 ! schwarze 224: Guidelines for writing
1.1 schwarze 225: man pages can be found in
226: .Xr mdoc 7 .
227: .Pp
228: If both a formatted and an unformatted version of the same manual page,
229: for example
230: .Pa cat1/foo.0
231: and
232: .Pa man1/foo.1 ,
233: exist in the same directory, and at least one of them is selected,
234: only the newer one is used.
235: However, if both the
236: .Fl a
237: and the
238: .Fl w
239: options are specified, both file names are printed.
240: .Sh ENVIRONMENT
241: .Bl -tag -width MANPATHX
242: .It Ev MACHINE
243: As some manual pages are intended only for specific architectures,
244: .Nm
245: searches any subdirectories,
246: with the same name as the current architecture,
247: in every directory which it searches.
248: Machine specific areas are checked before general areas.
249: The current machine type may be overridden by setting the environment
250: variable
251: .Ev MACHINE
252: to the name of a specific architecture,
253: or with the
254: .Fl S
255: option.
256: .Ev MACHINE
257: is case insensitive.
258: .It Ev MANPAGER
259: Any non-empty value of the environment variable
260: .Ev MANPAGER
261: will be used instead of the standard pagination program,
262: .Xr more 1 .
263: .It Ev MANPATH
264: The standard search path used by
265: .Nm
266: may be overridden by specifying a path in the
267: .Ev MANPATH
268: environment
269: variable.
270: The format of the path is a colon
271: .Pq Ql \&:
272: separated list of directories.
273: The subdirectories to be searched, as well as their search order,
274: are specified by the
275: .Dq _subdir
276: line in the
277: .Nm
278: configuration file.
279: .It Ev PAGER
280: Specifies the pagination program to use when
281: .Ev MANPAGER
282: is not defined.
283: If neither PAGER nor MANPAGER is defined,
284: .Pa /usr/bin/more Fl s
285: will be used.
286: .El
287: .Sh FILES
288: .Bl -tag -width /etc/man.conf -compact
289: .It Pa /etc/man.conf
290: default man configuration file
291: .El
292: .Sh EXIT STATUS
293: .Ex -std man
294: .Sh SEE ALSO
295: .Xr apropos 1 ,
296: .Xr intro 1 ,
297: .Xr whatis 1 ,
298: .Xr whereis 1 ,
299: .Xr intro 2 ,
300: .Xr intro 3 ,
301: .Xr intro 4 ,
302: .Xr intro 5 ,
303: .Xr man.conf 5 ,
304: .Xr intro 6 ,
305: .Xr intro 7 ,
306: .Xr mdoc 7 ,
307: .Xr intro 8 ,
308: .Xr intro 9
309: .Sh STANDARDS
310: The
311: .Nm
312: utility is compliant with the
313: .St -p1003.1-2008
314: specification.
315: .Pp
316: The flags
317: .Op Fl aCcfhMmSsw ,
318: as well as the environment variables
319: .Ev MACHINE ,
320: .Ev MANPAGER ,
321: and
322: .Ev MANPATH ,
323: are extensions to that specification.
324: .Sh HISTORY
325: A
326: .Nm
327: command first appeared in
328: .At v3 .
329: .Pp
330: The
331: .Fl w
332: option first appeared in
333: .At v7 ;
334: .Fl f
335: and
336: .Fl k
337: in
338: .Bx 4 ;
339: .Fl M
340: in
341: .Bx 4.3 ;
342: .Fl a
343: in
344: .Bx 4.3 Tahoe ;
345: .Fl c
346: and
347: .Fl m
348: in
349: .Bx 4.3 Reno ;
350: .Fl h
351: in
352: .Bx 4.3 Net/2 ;
353: .Fl C
354: in
355: .Nx 1.0 ;
356: and
357: .Fl s
358: and
359: .Fl S
360: in
361: .Ox 2.3 .
CVSweb