=================================================================== RCS file: /cvs/mandoc/man.1,v retrieving revision 1.1 retrieving revision 1.15 diff -u -p -r1.1 -r1.15 --- mandoc/man.1 2014/08/21 00:42:38 1.1 +++ mandoc/man.1 2015/07/17 22:38:29 1.15 @@ -1,7 +1,9 @@ -.\" $OpenBSD: man.1,v 1.1 2014/08/21 00:42:38 schwarze Exp $ +.\" $Id: man.1,v 1.15 2015/07/17 22:38:29 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, 2015 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: July 17 2015 $ .Dt MAN 1 .Os .Sh NAME @@ -37,24 +39,24 @@ .Nd display manual pages .Sh SYNOPSIS .Nm man -.Op Fl achw +.Op Fl acfhklw .Op Fl C Ar file +.Op Fl I Cm os Ns = Ns Ar name +.Op Fl K Ar encoding .Op Fl M Ar path .Op Fl m Ar path +.Op Fl O Ar option Ns = Ns Ar value .Op Fl S Ar subsection .Op Fl s Ar section +.Op Fl T Ar output +.Op Fl W Ar level .Op 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 @@ -86,56 +88,80 @@ 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 +.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. +This overrides any earlier +.Fl k +and +.Fl l +options. +.It Fl I Cm os Ns = Ns Ar name +Override the default operating system +.Ar name +for the +.Xr mdoc 7 +.Ic \&Os +and for the +.Xr man 7 +.Ic \&TH +macro. .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 Ar encoding +Specify the input encoding. +The supported +.Ar encoding +arguments are +.Cm us-ascii , +.Cm iso-8859-1 , +and +.Cm utf-8 . +By default, the encoding is automatically detected as described in the +.Xr mandoc 1 +manual. +.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. +This overrides any earlier +.Fl f +and +.Fl l +options. +.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 , +and +.Ar subsection +are ignored. +This overrides any earlier +.Fl f , +.Fl k , +and +.Fl w +options. .It Fl M Ar path Override the list of standard directories which .Nm @@ -174,6 +200,11 @@ are specified by the line in the .Nm configuration file. +.It Fl O Ar option Ns = Ns Ar value +Comma-separated output options. +For each output format, the available options are described in the +.Xr mandoc 1 +manual. .It Fl S Ar subsection Restricts the directories that .Nm @@ -243,6 +274,43 @@ specifies the possible .Ar section values, and their search order. Additional sections may be specified. +.It Fl T Ar output +Select the output format. +The default is +.Cm locale . +The other output modes +.Cm ascii , +.Cm html , +.Cm lint , +.Cm man , +.Cm pdf , +.Cm ps , +.Cm tree , +and +.Cm utf8 +are described in the +.Xr mandoc 1 +manual. +.It Fl W Ar level +Specify the minimum message +.Ar level +to be reported on the standard error output and to affect the exit status. +The +.Ar level +can be +.Cm warning , +.Cm error , +or +.Cm unsupp ; +.Cm all +is an alias for +.Cm warning . +By default, +.Nm +is silent. +See the +.Xr mandoc 1 +manual for details. .It Fl w List the pathnames of the manual pages which .Nm @@ -253,8 +321,7 @@ and combination. .El .Pp -Guidelines for -.Ox +Guidelines for writing man pages can be found in .Xr mdoc 7 . .Pp @@ -293,6 +360,13 @@ Any non-empty value of the environment variable .Ev MANPAGER will be 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, +and environment variables. .It Ev MANPATH The standard search path used by .Nm @@ -314,7 +388,8 @@ 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 +.Xr more 1 +.Fl s will be used. .El .Sh FILES @@ -347,7 +422,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 ,