Annotation of mandoc/man.1, Revision 1.6
1.6 ! schwarze 1: .\" $Id: man.1,v 1.5 2014/09/03 05:22:45 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.6 ! schwarze 34: .Dd $Mdocdate: September 3 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
44: .Op Fl M Ar path
45: .Op Fl m Ar path
46: .Op Fl S Ar subsection
47: .Op Fl s Ar section
48: .Op Ar section
49: .Ar name ...
50: .Sh DESCRIPTION
51: The
52: .Nm
53: utility
54: displays the
55: manual pages entitled
56: .Ar name .
57: Pages may be selected according to
58: a specific category
59: .Pq Ar section
60: or
61: machine architecture
62: .Pq Ar subsection .
63: .Pp
64: The options are as follows:
65: .Bl -tag -width Ds
66: .It Fl a
67: Display all of the manual pages for a specified
68: .Ar section
69: and
70: .Ar name
71: combination.
72: Normally, only the first manual page found is displayed.
73: .It Fl C Ar file
74: Use the specified
75: .Ar file
76: instead of the default configuration file.
77: This permits users to configure their own manual environment.
78: See
79: .Xr man.conf 5
80: for a description of the contents of this file.
81: .It Fl c
82: Copy the manual page to the standard output instead of using
83: .Xr more 1
84: to paginate it.
85: This is done by default if the standard output is not a terminal device.
1.2 schwarze 86: .It Fl f
1.1 schwarze 87: A synonym for
88: .Xr whatis 1 .
1.2 schwarze 89: It searches for
90: .Ar name
91: in manual page names and displays the header lines from all matching pages.
92: The search is case insensitive and matches whole words only.
1.4 schwarze 93: This overrides any earlier
94: .Fl k
95: and
96: .Fl l
97: options.
1.1 schwarze 98: .It Fl h
1.5 schwarze 99: Display only the SYNOPSIS lines of the requested manual pages.
100: Implies
101: .Fl a .
1.2 schwarze 102: .It Fl k
1.1 schwarze 103: A synonym for
104: .Xr apropos 1 .
1.2 schwarze 105: Instead of
106: .Ar name ,
107: an expression can be provided using the syntax described in the
108: .Xr apropos 1
109: manual.
110: By default, it displays the header lines of all matching pages.
1.4 schwarze 111: This overrides any earlier
112: .Fl f
113: and
114: .Fl l
115: options.
116: .It Fl l
117: A synonym for
118: .Xr mandoc 1
119: .Fl a .
120: The
121: .Ar name
122: arguments are interpreted as filenames.
123: No search is done and
124: .Ar file ,
125: .Ar path ,
126: .Ar section ,
127: and
128: .Ar subsection
129: are ignored.
130: This overrides any earlier
131: .Fl f ,
132: .Fl k ,
133: and
134: .Fl w
135: options.
1.1 schwarze 136: .It Fl M Ar path
137: Override the list of standard directories which
138: .Nm
139: searches for manual pages.
140: The supplied
141: .Ar path
142: must be a colon
143: .Pq Ql \&:
144: separated list of directories.
145: This search path may also be set using the environment variable
146: .Ev MANPATH .
147: The subdirectories to be searched, and their search order,
148: are specified by the
149: .Dq _subdir
150: line in the
151: .Nm
152: configuration file.
153: .It Fl m Ar path
154: Augment the list of standard directories which
155: .Nm
156: searches for manual pages.
157: The supplied
158: .Ar path
159: must be a colon
160: .Pq Ql \&:
161: separated list of directories.
162: These directories will be searched before the standard directories or
163: the directories specified using the
164: .Fl M
165: option or the
166: .Ev MANPATH
167: environment variable.
168: The subdirectories to be searched, and their search order,
169: are specified by the
170: .Dq _subdir
171: line in the
172: .Nm
173: configuration file.
174: .It Fl S Ar subsection
175: Restricts the directories that
176: .Nm
177: will search to those of a specific
178: .Xr machine 1
179: architecture.
180: .Ar subsection
181: is case insensitive.
182: .Pp
183: By default manual pages for all architectures are installed.
184: Therefore this option can be used to view pages for one
185: architecture whilst using another.
186: .Pp
187: This option overrides the
188: .Ev MACHINE
189: environment variable.
190: .It Xo
191: .Op Fl s
192: .Ar section
193: .Xc
194: Restricts the directories that
195: .Nm
196: will search to a specific section.
197: The currently available sections are:
198: .Pp
199: .Bl -tag -width "localXXX" -offset indent -compact
200: .It 1
201: General commands
202: .Pq tools and utilities .
203: .It 2
204: System calls and error numbers.
205: .It 3
206: Libraries.
207: .It 3f
208: Fortran programmer's reference guide.
209: .It 3p
210: .Xr perl 1
211: programmer's reference guide.
212: .It 4
213: Device drivers.
214: .It 5
215: File formats.
216: .It 6
217: Games.
218: .It 7
219: Miscellaneous.
220: .It 8
221: System maintenance and operation commands.
222: .It 9
223: Kernel internals.
224: .It X11
225: An alias for X11R6.
226: .It X11R6
227: X Window System.
228: .It local
229: Pages located in
230: .Pa /usr/local .
231: .It n
232: Tcl/Tk commands.
233: .El
234: .Pp
235: The
236: .Nm
237: configuration file,
238: .Xr man.conf 5 ,
239: specifies the possible
240: .Ar section
241: values, and their search order.
242: Additional sections may be specified.
1.4 schwarze 243: .It Fl V
244: Print version and exit.
1.1 schwarze 245: .It Fl w
246: List the pathnames of the manual pages which
247: .Nm
248: would display for the specified
249: .Ar section
250: and
251: .Ar name
252: combination.
253: .El
1.3 schwarze 254: .Pp
255: The
256: .Nm
257: utility also supports the options
1.6 ! schwarze 258: .Fl IKOTW
1.3 schwarze 259: described in the
260: .Xr mandoc 1
261: manual.
1.1 schwarze 262: .Pp
1.2 schwarze 263: Guidelines for writing
1.1 schwarze 264: man pages can be found in
265: .Xr mdoc 7 .
266: .Pp
267: If both a formatted and an unformatted version of the same manual page,
268: for example
269: .Pa cat1/foo.0
270: and
271: .Pa man1/foo.1 ,
272: exist in the same directory, and at least one of them is selected,
273: only the newer one is used.
274: However, if both the
275: .Fl a
276: and the
277: .Fl w
278: options are specified, both file names are printed.
279: .Sh ENVIRONMENT
280: .Bl -tag -width MANPATHX
281: .It Ev MACHINE
282: As some manual pages are intended only for specific architectures,
283: .Nm
284: searches any subdirectories,
285: with the same name as the current architecture,
286: in every directory which it searches.
287: Machine specific areas are checked before general areas.
288: The current machine type may be overridden by setting the environment
289: variable
290: .Ev MACHINE
291: to the name of a specific architecture,
292: or with the
293: .Fl S
294: option.
295: .Ev MACHINE
296: is case insensitive.
297: .It Ev MANPAGER
298: Any non-empty value of the environment variable
299: .Ev MANPAGER
300: will be used instead of the standard pagination program,
301: .Xr more 1 .
302: .It Ev MANPATH
303: The standard search path used by
304: .Nm
305: may be overridden by specifying a path in the
306: .Ev MANPATH
307: environment
308: variable.
309: The format of the path is a colon
310: .Pq Ql \&:
311: separated list of directories.
312: The subdirectories to be searched, as well as their search order,
313: are specified by the
314: .Dq _subdir
315: line in the
316: .Nm
317: configuration file.
318: .It Ev PAGER
319: Specifies the pagination program to use when
320: .Ev MANPAGER
321: is not defined.
322: If neither PAGER nor MANPAGER is defined,
323: .Pa /usr/bin/more Fl s
324: will be used.
325: .El
326: .Sh FILES
327: .Bl -tag -width /etc/man.conf -compact
328: .It Pa /etc/man.conf
329: default man configuration file
330: .El
331: .Sh EXIT STATUS
332: .Ex -std man
333: .Sh SEE ALSO
334: .Xr apropos 1 ,
335: .Xr intro 1 ,
336: .Xr whatis 1 ,
337: .Xr whereis 1 ,
338: .Xr intro 2 ,
339: .Xr intro 3 ,
340: .Xr intro 4 ,
341: .Xr intro 5 ,
342: .Xr man.conf 5 ,
343: .Xr intro 6 ,
344: .Xr intro 7 ,
345: .Xr mdoc 7 ,
346: .Xr intro 8 ,
347: .Xr intro 9
348: .Sh STANDARDS
349: The
350: .Nm
351: utility is compliant with the
352: .St -p1003.1-2008
353: specification.
354: .Pp
355: The flags
356: .Op Fl aCcfhMmSsw ,
357: as well as the environment variables
358: .Ev MACHINE ,
359: .Ev MANPAGER ,
360: and
361: .Ev MANPATH ,
362: are extensions to that specification.
363: .Sh HISTORY
364: A
365: .Nm
366: command first appeared in
367: .At v3 .
368: .Pp
369: The
370: .Fl w
371: option first appeared in
372: .At v7 ;
373: .Fl f
374: and
375: .Fl k
376: in
377: .Bx 4 ;
378: .Fl M
379: in
380: .Bx 4.3 ;
381: .Fl a
382: in
383: .Bx 4.3 Tahoe ;
384: .Fl c
385: and
386: .Fl m
387: in
388: .Bx 4.3 Reno ;
389: .Fl h
390: in
391: .Bx 4.3 Net/2 ;
392: .Fl C
393: in
394: .Nx 1.0 ;
395: and
396: .Fl s
397: and
398: .Fl S
399: in
400: .Ox 2.3 .
CVSweb