===================================================================
RCS file: /cvs/mandoc/man.1,v
retrieving revision 1.17
retrieving revision 1.24
diff -u -p -r1.17 -r1.24
--- mandoc/man.1	2016/07/01 20:24:04	1.17
+++ mandoc/man.1	2017/03/21 18:06:12	1.24
@@ -1,9 +1,9 @@
-.\"	$Id: man.1,v 1.17 2016/07/01 20:24:04 schwarze Exp $
+.\"	$Id: man.1,v 1.24 2017/03/21 18:06:12 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 <jmc@openbsd.org>
-.\" Copyright (c) 2010, 2011, 2014, 2015 Ingo Schwarze <schwarze@openbsd.org>
+.\" Copyright (c) 2010, 2011, 2014-2017 Ingo Schwarze <schwarze@openbsd.org>
 .\"
 .\" Redistribution and use in source and binary forms, with or without
 .\" modification, are permitted provided that the following conditions
@@ -31,7 +31,7 @@
 .\"
 .\"     @(#)man.1	8.2 (Berkeley) 1/2/94
 .\"
-.Dd $Mdocdate: July 1 2016 $
+.Dd $Mdocdate: March 21 2017 $
 .Dt MAN 1
 .Os
 .Sh NAME
@@ -69,12 +69,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
@@ -100,6 +96,12 @@ This overrides any earlier
 and
 .Fl l
 options.
+.It Fl h
+Display only the SYNOPSIS lines of the requested manual pages.
+Implies
+.Fl a
+and
+.Fl c .
 .It Fl I Cm os Ns = Ns Ar name
 Override the default operating system
 .Ar name
@@ -110,12 +112,6 @@ and for the
 .Xr man 7
 .Ic \&TH
 macro.
-.It Fl h
-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
@@ -238,6 +234,10 @@ System maintenance and operation commands.
 .It 9
 Kernel internals.
 .El
+.Pp
+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 T Ar output
 Select the output format.
 The default is
@@ -294,13 +294,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
@@ -322,7 +316,7 @@ 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
@@ -330,17 +324,43 @@ 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.
+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.
+Invalid paths, or paths without manual databases, 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
@@ -348,7 +368,12 @@ is not defined.
 If neither PAGER nor MANPAGER is defined,
 .Xr more 1
 .Fl s
-will be used.
+is used.
+Only used if
+.Fl a
+or
+.Fl l
+is specified.
 .El
 .Sh FILES
 .Bl -tag -width /etc/man.conf -compact
@@ -419,9 +444,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 .