Annotation of src/usr.bin/mandoc/man.1, Revision 1.40
1.40 ! schwarze 1: .\" $OpenBSD: man.1,v 1.39 2020/07/20 14:52:12 schwarze Exp $
1.1 schwarze 2: .\"
3: .\" Copyright (c) 1989, 1990, 1993
4: .\" The Regents of the University of California. All rights reserved.
5: .\" Copyright (c) 2003, 2007, 2008, 2014 Jason McIntyre <jmc@openbsd.org>
1.36 schwarze 6: .\" Copyright (c) 2010, 2011, 2014-2020 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.39 schwarze 34: .Dd $Mdocdate: July 20 2020 $
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.11 schwarze 42: .Op Fl acfhklw
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
1.26 schwarze 47: .Op Oo Fl s Oc Ar section
1.1 schwarze 48: .Ar name ...
49: .Sh DESCRIPTION
50: The
51: .Nm
52: utility
53: displays the
1.34 schwarze 54: manual page entitled
1.1 schwarze 55: .Ar name .
56: Pages may be selected according to
57: a specific category
58: .Pq Ar section
59: or
60: machine architecture
61: .Pq Ar subsection .
62: .Pp
63: The options are as follows:
64: .Bl -tag -width Ds
65: .It Fl a
1.16 schwarze 66: Display all matching manual pages.
1.1 schwarze 67: .It Fl C Ar file
68: Use the specified
69: .Ar file
70: instead of the default configuration file.
71: This permits users to configure their own manual environment.
72: See
73: .Xr man.conf 5
74: for a description of the contents of this file.
75: .It Fl c
76: Copy the manual page to the standard output instead of using
1.39 schwarze 77: .Xr less 1
1.1 schwarze 78: to paginate it.
79: This is done by default if the standard output is not a terminal device.
1.28 schwarze 80: .Pp
81: When using
82: .Fl c ,
83: most terminal devices are unable to show the markup.
84: To print the output of
85: .Nm
86: to the terminal with markup but without using a pager, pipe it to
87: .Xr ul 1 .
88: To remove the markup, pipe the output to
89: .Xr col 1
90: .Fl b
91: instead.
1.1 schwarze 92: .It Fl f
93: A synonym for
94: .Xr whatis 1 .
95: It searches for
96: .Ar name
97: in manual page names and displays the header lines from all matching pages.
98: The search is case insensitive and matches whole words only.
1.18 jmc 99: .It Fl h
100: Display only the SYNOPSIS lines of the requested manual pages.
101: Implies
102: .Fl a
103: and
104: .Fl c .
1.1 schwarze 105: .It Fl k
106: A synonym for
107: .Xr apropos 1 .
108: Instead of
109: .Ar name ,
110: an expression can be provided using the syntax described in the
111: .Xr apropos 1
112: manual.
113: By default, it displays the header lines of all matching pages.
1.2 schwarze 114: .It Fl l
115: A synonym for
1.31 schwarze 116: .Xr mandoc 1 .
1.2 schwarze 117: The
118: .Ar name
119: arguments are interpreted as filenames.
120: No search is done and
121: .Ar file ,
122: .Ar path ,
123: .Ar section ,
1.25 schwarze 124: .Ar subsection ,
1.2 schwarze 125: and
1.25 schwarze 126: .Fl w
1.2 schwarze 127: are ignored.
1.31 schwarze 128: This option implies
129: .Fl a .
1.1 schwarze 130: .It Fl M Ar path
1.34 schwarze 131: Override the list of directories to search for manual pages.
1.1 schwarze 132: The supplied
133: .Ar path
134: must be a colon
135: .Pq Ql \&:
136: separated list of directories.
1.34 schwarze 137: This option also overrides the environment variable
138: .Ev MANPATH
139: and any directories specified in the
140: .Xr man.conf 5
141: file.
1.1 schwarze 142: .It Fl m Ar path
1.34 schwarze 143: Augment the list of directories to search for manual pages.
1.1 schwarze 144: The supplied
145: .Ar path
146: must be a colon
147: .Pq Ql \&:
148: separated list of directories.
1.34 schwarze 149: These directories will be searched before those specified using the
1.1 schwarze 150: .Fl M
1.34 schwarze 151: option, the
1.1 schwarze 152: .Ev MANPATH
1.34 schwarze 153: environment variable, the
154: .Xr man.conf 5
155: file, or the default directories.
1.1 schwarze 156: .It Fl S Ar subsection
1.23 schwarze 157: Only show pages for the specified
1.1 schwarze 158: .Xr machine 1
159: architecture.
160: .Ar subsection
161: is case insensitive.
162: .Pp
163: By default manual pages for all architectures are installed.
164: Therefore this option can be used to view pages for one
165: architecture whilst using another.
166: .Pp
167: This option overrides the
168: .Ev MACHINE
169: environment variable.
1.37 schwarze 170: .Tg s
1.15 schwarze 171: .It Oo Fl s Oc Ar section
172: Only select manuals from the specified
173: .Ar section .
1.1 schwarze 174: The currently available sections are:
175: .Pp
176: .Bl -tag -width "localXXX" -offset indent -compact
177: .It 1
178: General commands
179: .Pq tools and utilities .
180: .It 2
181: System calls and error numbers.
182: .It 3
1.15 schwarze 183: Library functions.
1.1 schwarze 184: .It 3p
185: .Xr perl 1
186: programmer's reference guide.
187: .It 4
188: Device drivers.
189: .It 5
190: File formats.
191: .It 6
192: Games.
193: .It 7
1.15 schwarze 194: Miscellaneous information.
1.1 schwarze 195: .It 8
196: System maintenance and operation commands.
197: .It 9
198: Kernel internals.
199: .El
200: .It Fl w
1.23 schwarze 201: List the pathnames of all matching manual pages instead of displaying
202: any of them.
1.36 schwarze 203: If no
204: .Ar name
205: is given, list the directories that would be searched.
1.1 schwarze 206: .El
1.24 schwarze 207: .Pp
208: The options
209: .Fl IKOTW
210: are also supported and are documented in
211: .Xr mandoc 1 .
1.25 schwarze 212: The options
213: .Fl fkl
214: are mutually exclusive and override each other.
1.1 schwarze 215: .Pp
1.34 schwarze 216: The search starts with the
217: .Fl m
218: argument if provided, then continues with the
219: .Fl M
220: argument, the
221: .Ev MANPATH
222: variable, the
223: .Ic manpath
224: entries in the
225: .Xr man.conf 5
226: file, or with
227: .Pa /usr/share/man : Ns Pa /usr/X11R6/man : Ns Pa /usr/local/man
228: by default.
229: Within each of these, directories are searched in the order provided.
230: Within each directory, the search proceeds according to the following
231: list of sections: 1, 8, 6, 2, 3, 5, 7, 4, 9, 3p.
232: The first match found is shown.
1.1 schwarze 233: .Pp
1.33 schwarze 234: The
235: .Xr mandoc.db 5
236: database is used for looking up manual page entries.
237: In cases where the database is absent, outdated, or corrupt,
238: .Nm
239: falls back to looking for files called
240: .Ar name . Ns Ar section .
1.1 schwarze 241: If both a formatted and an unformatted version of the same manual page,
242: for example
243: .Pa cat1/foo.0
244: and
245: .Pa man1/foo.1 ,
1.22 schwarze 246: exist in the same directory, only the unformatted version is used.
1.33 schwarze 247: The database is kept up to date with
248: .Xr makewhatis 8 ,
249: which is run by the
250: .Xr weekly 8
251: maintenance script.
1.34 schwarze 252: .Pp
253: Guidelines for writing
254: man pages can be found in
255: .Xr mdoc 7 .
1.1 schwarze 256: .Sh ENVIRONMENT
257: .Bl -tag -width MANPATHX
258: .It Ev MACHINE
259: As some manual pages are intended only for specific architectures,
260: .Nm
261: searches any subdirectories,
262: with the same name as the current architecture,
263: in every directory which it searches.
264: Machine specific areas are checked before general areas.
265: The current machine type may be overridden by setting the environment
266: variable
267: .Ev MACHINE
268: to the name of a specific architecture,
269: or with the
270: .Fl S
271: option.
272: .Ev MACHINE
273: is case insensitive.
274: .It Ev MANPAGER
275: Any non-empty value of the environment variable
276: .Ev MANPAGER
1.21 schwarze 277: is used instead of the standard pagination program,
1.38 schwarze 278: .Xr less 1 .
1.13 schwarze 279: If
280: .Xr less 1
281: is used, the interactive
282: .Ic :t
283: command can be used to go to the definitions of various terms, for
284: example command line options, command modifiers, internal commands,
1.17 schwarze 285: environment variables, function names, preprocessor macros,
286: .Xr errno 2
287: values, and some other emphasized words.
288: Some terms may have defining text at more than one place.
289: In that case, the
290: .Xr less 1
291: interactive commands
292: .Ic t
293: and
294: .Ic T
295: can be used to move to the next and to the previous place providing
296: information about the term last searched for with
297: .Ic :t .
1.32 schwarze 298: The
299: .Fl O Cm tag Ns Op = Ns Ar term
300: option documented in the
301: .Xr mandoc 1
302: manual opens a manual page at the definition of a specific
303: .Ar term
304: rather than at the beginning.
1.1 schwarze 305: .It Ev MANPATH
1.34 schwarze 306: Override the standard search path which is either specified in
307: .Xr man.conf 5
308: or the default path.
309: The format of
1.1 schwarze 310: .Ev MANPATH
1.34 schwarze 311: is a colon
1.1 schwarze 312: .Pq Ql \&:
313: separated list of directories.
1.34 schwarze 314: Invalid directories are ignored.
1.21 schwarze 315: Overridden by
316: .Fl M ,
317: ignored if
318: .Fl l
319: is specified.
320: .Pp
321: If
322: .Ev MANPATH
1.34 schwarze 323: begins with a colon, it is appended to the standard path;
324: if it ends with a colon, it is prepended to the standard path;
1.21 schwarze 325: or if it contains two adjacent colons,
1.34 schwarze 326: the standard path is inserted between the colons.
1.1 schwarze 327: .It Ev PAGER
328: Specifies the pagination program to use when
329: .Ev MANPAGER
330: is not defined.
331: If neither PAGER nor MANPAGER is defined,
1.38 schwarze 332: .Xr less 1
1.21 schwarze 333: is used.
1.1 schwarze 334: .El
335: .Sh FILES
336: .Bl -tag -width /etc/man.conf -compact
337: .It Pa /etc/man.conf
1.34 schwarze 338: default
339: .Nm
340: configuration file
1.1 schwarze 341: .El
342: .Sh EXIT STATUS
343: .Ex -std man
1.23 schwarze 344: See
345: .Xr mandoc 1
346: for details.
1.29 schwarze 347: .Sh EXAMPLES
348: Format a page for pasting extracts into an email message \(em
349: avoid printing any UTF-8 characters, reduce the width to ease
350: quoting in replies, and remove markup:
351: .Pp
352: .Dl $ man -T ascii -O width=65 pledge | col -b
353: .Pp
354: Read a typeset page in a PDF viewer:
355: .Pp
356: .Dl $ MANPAGER=mupdf man -T pdf lpd
1.1 schwarze 357: .Sh SEE ALSO
358: .Xr apropos 1 ,
1.28 schwarze 359: .Xr col 1 ,
360: .Xr mandoc 1 ,
361: .Xr ul 1 ,
1.1 schwarze 362: .Xr whereis 1 ,
363: .Xr man.conf 5 ,
1.28 schwarze 364: .Xr mdoc 7
1.1 schwarze 365: .Sh STANDARDS
366: The
367: .Nm
368: utility is compliant with the
369: .St -p1003.1-2008
370: specification.
371: .Pp
372: The flags
1.11 schwarze 373: .Op Fl aCcfhIKlMmOSsTWw ,
1.1 schwarze 374: as well as the environment variables
375: .Ev MACHINE ,
376: .Ev MANPAGER ,
377: and
378: .Ev MANPATH ,
379: are extensions to that specification.
380: .Sh HISTORY
381: A
382: .Nm
383: command first appeared in
1.35 jsg 384: .At v2 .
1.1 schwarze 385: .Pp
386: The
387: .Fl w
388: option first appeared in
389: .At v7 ;
390: .Fl f
391: and
392: .Fl k
393: in
1.40 ! schwarze 394: .Pa /usr/usb/man
! 395: in
! 396: .Bx 4.0 ;
1.1 schwarze 397: .Fl M
398: in
399: .Bx 4.3 ;
400: .Fl a
401: in
402: .Bx 4.3 Tahoe ;
403: .Fl c
404: and
405: .Fl m
406: in
407: .Bx 4.3 Reno ;
408: .Fl h
409: in
410: .Bx 4.3 Net/2 ;
411: .Fl C
412: in
413: .Nx 1.0 ;
414: .Fl s
415: and
416: .Fl S
417: in
1.19 schwarze 418: .Ox 2.3 ;
419: and
420: .Fl I ,
421: .Fl K ,
422: .Fl l ,
423: .Fl O ,
424: and
425: .Fl W
426: in
427: .Ox 5.7 .
428: The
429: .Fl T
430: option first appeared in
431: .At III
432: and was also added in
433: .Ox 5.7 .