=================================================================== RCS file: /cvs/mandoc/man.1,v retrieving revision 1.1 retrieving revision 1.30 diff -u -p -r1.1 -r1.30 --- mandoc/man.1 2014/08/21 00:42:38 1.1 +++ mandoc/man.1 2017/08/09 12:49:04 1.30 @@ -1,7 +1,9 @@ -.\" $OpenBSD: man.1,v 1.1 2014/08/21 00:42:38 schwarze Exp $ +.\" $Id: man.1,v 1.30 2017/08/09 12:49:04 schwarze Exp $ .\" .\" Copyright (c) 1989, 1990, 1993 .\" The Regents of the University of California. All rights reserved. +.\" Copyright (c) 2003, 2007, 2008, 2014 Jason McIntyre +.\" Copyright (c) 2010, 2011, 2014-2017 Ingo Schwarze .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions @@ -29,7 +31,7 @@ .\" .\" @(#)man.1 8.2 (Berkeley) 1/2/94 .\" -.Dd $Mdocdate: August 21 2014 $ +.Dd $Mdocdate: August 9 2017 $ .Dt MAN 1 .Os .Sh NAME @@ -37,24 +39,18 @@ .Nd display manual pages .Sh SYNOPSIS .Nm man -.Op Fl achw +.Op Fl acfhklw .Op Fl C Ar file .Op Fl M Ar path .Op Fl m Ar path .Op Fl S Ar subsection -.Op Fl s Ar section -.Op Ar section +.Op Oo Fl s Oc Ar section .Ar name ... -.Nm man -.Fl f Ar command ... -.Nm man -.Fl k Ar keyword ... .Sh DESCRIPTION The .Nm utility displays the -.Bx manual pages entitled .Ar name . Pages may be selected according to @@ -67,12 +63,8 @@ machine architecture The options are as follows: .Bl -tag -width Ds .It Fl a -Display all of the manual pages for a specified -.Ar section -and -.Ar name -combination. -Normally, only the first manual page found is displayed. +Display all matching manual pages. +Normally, only the first page found is displayed. .It Fl C Ar file Use the specified .Ar file @@ -86,56 +78,55 @@ Copy the manual page to the standard output instead of .Xr more 1 to paginate it. This is done by default if the standard output is not a terminal device. -.It Fl f Ar command +.Pp +When using +.Fl c , +most terminal devices are unable to show the markup. +To print the output of +.Nm +to the terminal with markup but without using a pager, pipe it to +.Xr ul 1 . +To remove the markup, pipe the output to +.Xr col 1 +.Fl b +instead. +.It Fl f A synonym for .Xr whatis 1 . -It looks up a given command and -gives the header line from the manual page. -.Ar command -is case insensitive. +It searches for +.Ar name +in manual page names and displays the header lines from all matching pages. +The search is case insensitive and matches whole words only. .It Fl h -Display only the -.Dq SYNOPSIS -lines of the requested manual pages. -.It Fl k Ar keyword +Display only the SYNOPSIS lines of the requested manual pages. +Implies +.Fl a +and +.Fl c . +.It Fl k A synonym for .Xr apropos 1 . -It shows which manual pages contain instances of any of the given -keywords in their title line. -.Ar keyword -is case insensitive. -.Pp -For instance, -to list all man pages which contain -.Dq mount -in the -.Dq NAME -line of the man page: -.Pp -.Dl $ man -k mount -.Pp -Which would produce a list much like this: -.Bd -literal -amd (8) \(en automatically mount file systems -amq (8) \(en automounter query tool -domountroothooks (9) \(en run all mountroot hooks -exports (5) \(en define remote mount points for NFS mount requests -getfsstat (2) \(en get list of all mounted file systems -getmntinfo (3) \(en get information about mounted file systems -mount (8) \(en mount file systems -mount, unmount (2) \(en mount or dismount a filesystem -mount_cd9660 (8) \(en mount an ISO-9660 filesystem -mount_ext2fs (8) \(en mount an ext2fs file system -mount_ffs (8) \(en mount a Berkeley Fast File System -mount_msdos (8) \(en mount an MS-DOS file system -mount_nfs (8) \(en mount NFS file systems -mount_ntfs (8) \(en mount an NTFS file system -mount_procfs (8) \(en mount the process file system -mount_udf (8) \(en mount a UDF filesystem -mount_vnd, vnconfig (8) \(en configure vnode disks -mountd (8) \(en service remote NFS mount requests -\&... -.Ed +Instead of +.Ar name , +an expression can be provided using the syntax described in the +.Xr apropos 1 +manual. +By default, it displays the header lines of all matching pages. +.It Fl l +A synonym for +.Xr mandoc 1 +.Fl a . +The +.Ar name +arguments are interpreted as filenames. +No search is done and +.Ar file , +.Ar path , +.Ar section , +.Ar subsection , +and +.Fl w +are ignored. .It Fl M Ar path Override the list of standard directories which .Nm @@ -147,12 +138,6 @@ must be a colon separated list of directories. This search path may also be set using the environment variable .Ev MANPATH . -The subdirectories to be searched, and their search order, -are specified by the -.Dq _subdir -line in the -.Nm -configuration file. .It Fl m Ar path Augment the list of standard directories which .Nm @@ -168,16 +153,8 @@ the directories specified using the option or the .Ev MANPATH environment variable. -The subdirectories to be searched, and their search order, -are specified by the -.Dq _subdir -line in the -.Nm -configuration file. .It Fl S Ar subsection -Restricts the directories that -.Nm -will search to those of a specific +Only show pages for the specified .Xr machine 1 architecture. .Ar subsection @@ -190,13 +167,9 @@ architecture whilst using another. This option overrides the .Ev MACHINE environment variable. -.It Xo -.Op Fl s -.Ar section -.Xc -Restricts the directories that -.Nm -will search to a specific section. +.It Oo Fl s Oc Ar section +Only select manuals from the specified +.Ar section . The currently available sections are: .Pp .Bl -tag -width "localXXX" -offset indent -compact @@ -206,9 +179,7 @@ General commands .It 2 System calls and error numbers. .It 3 -Libraries. -.It 3f -Fortran programmer's reference guide. +Library functions. .It 3p .Xr perl 1 programmer's reference guide. @@ -219,42 +190,30 @@ File formats. .It 6 Games. .It 7 -Miscellaneous. +Miscellaneous information. .It 8 System maintenance and operation commands. .It 9 Kernel internals. -.It X11 -An alias for X11R6. -.It X11R6 -X Window System. -.It local -Pages located in -.Pa /usr/local . -.It n -Tcl/Tk commands. .El .Pp -The -.Nm -configuration file, -.Xr man.conf 5 , -specifies the possible -.Ar section -values, and their search order. -Additional sections may be specified. +If not specified and a match is found in more than one section, +the first match is selected from the following list: +1, 8, 6, 2, 3, 5, 7, 4, 9, 3p. .It Fl w -List the pathnames of the manual pages which -.Nm -would display for the specified -.Ar section -and -.Ar name -combination. +List the pathnames of all matching manual pages instead of displaying +any of them. .El .Pp -Guidelines for -.Ox +The options +.Fl IKOTW +are also supported and are documented in +.Xr mandoc 1 . +The options +.Fl fkl +are mutually exclusive and override each other. +.Pp +Guidelines for writing man pages can be found in .Xr mdoc 7 . .Pp @@ -263,13 +222,7 @@ for example .Pa cat1/foo.0 and .Pa man1/foo.1 , -exist in the same directory, and at least one of them is selected, -only the newer one is used. -However, if both the -.Fl a -and the -.Fl w -options are specified, both file names are printed. +exist in the same directory, only the unformatted version is used. .Sh ENVIRONMENT .Bl -tag -width MANPATHX .It Ev MACHINE @@ -291,31 +244,64 @@ is case insensitive. .It Ev MANPAGER Any non-empty value of the environment variable .Ev MANPAGER -will be used instead of the standard pagination program, +is used instead of the standard pagination program, .Xr more 1 . +If +.Xr less 1 +is used, the interactive +.Ic :t +command can be used to go to the definitions of various terms, for +example command line options, command modifiers, internal commands, +environment variables, function names, preprocessor macros, +.Xr errno 2 +values, and some other emphasized words. +Some terms may have defining text at more than one place. +In that case, the +.Xr less 1 +interactive commands +.Ic t +and +.Ic T +can be used to move to the next and to the previous place providing +information about the term last searched for with +.Ic :t . .It Ev MANPATH The standard search path used by .Nm -may be overridden by specifying a path in the +may be changed by specifying a path in the .Ev MANPATH -environment -variable. +environment variable. The format of the path is a colon .Pq Ql \&: separated list of directories. -The subdirectories to be searched, as well as their search order, -are specified by the -.Dq _subdir -line in the -.Nm -configuration file. +Invalid paths are ignored. +Overridden by +.Fl M , +ignored if +.Fl l +is specified. +.Pp +If +.Ev MANPATH +begins with a colon, it is appended to the default list; +if it ends with a colon, it is prepended to the default list; +or if it contains two adjacent colons, +the standard search path is inserted between the colons. +If none of these conditions are met, it overrides the +standard search path. .It Ev PAGER Specifies the pagination program to use when .Ev MANPAGER is not defined. If neither PAGER nor MANPAGER is defined, -.Pa /usr/bin/more Fl s -will be used. +.Xr more 1 +.Fl s +is used. +Only used if +.Fl a +or +.Fl l +is specified. .El .Sh FILES .Bl -tag -width /etc/man.conf -compact @@ -324,21 +310,17 @@ default man configuration file .El .Sh EXIT STATUS .Ex -std man +See +.Xr mandoc 1 +for details. .Sh SEE ALSO .Xr apropos 1 , -.Xr intro 1 , -.Xr whatis 1 , +.Xr col 1 , +.Xr mandoc 1 , +.Xr ul 1 , .Xr whereis 1 , -.Xr intro 2 , -.Xr intro 3 , -.Xr intro 4 , -.Xr intro 5 , .Xr man.conf 5 , -.Xr intro 6 , -.Xr intro 7 , -.Xr mdoc 7 , -.Xr intro 8 , -.Xr intro 9 +.Xr mdoc 7 .Sh STANDARDS The .Nm @@ -347,7 +329,7 @@ utility is compliant with the specification. .Pp The flags -.Op Fl aCcfhMmSsw , +.Op Fl aCcfhIKlMmOSsTWw , as well as the environment variables .Ev MACHINE , .Ev MANPAGER , @@ -386,9 +368,23 @@ in .Fl C in .Nx 1.0 ; -and .Fl s and .Fl S in -.Ox 2.3 . +.Ox 2.3 ; +and +.Fl I , +.Fl K , +.Fl l , +.Fl O , +and +.Fl W +in +.Ox 5.7 . +The +.Fl T +option first appeared in +.At III +and was also added in +.Ox 5.7 .