Document man(1) section selection priority,

and correct description of apropos(1) output search order.
Suggested by tb@.

2 files changed, 32 insertions, 7 deletions

diff --git a/apropos.1 b/apropos.1
index 8f51030e..e3acec96 100644
--- a/apropos.1
+++ b/apropos.1
@@ -1,7 +1,7 @@
-.\"	$Id: apropos.1,v 1.40 2017/01/31 19:44:04 schwarze Exp $
+.\"	$Id: apropos.1,v 1.41 2017/03/17 17:24:41 schwarze Exp $
 .\"
 .\" Copyright (c) 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv>
-.\" Copyright (c) 2011, 2012, 2014 Ingo Schwarze <schwarze@openbsd.org>
+.\" Copyright (c) 2011, 2012, 2014, 2017 Ingo Schwarze <schwarze@openbsd.org>
 .\"
 .\" Permission to use, copy, modify, and distribute this software for any
 .\" purpose with or without fee is hereby granted, provided that the above
@@ -15,7 +15,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: January 31 2017 $
+.Dd $Mdocdate: March 17 2017 $
 .Dt APROPOS 1
 .Os
 .Sh NAME
@@ -237,7 +237,28 @@ is evaluated case-insensitively.
 Has no effect on substring terms.
 .El
 .Pp
-Results are sorted by manual sections and names, with output formatted as
+Results are sorted according to the following criteria:
+.Bl -enum
+.It
+The manpath directory tree the page is found in, according to the
+order specified with
+.Fl M ,
+.Fl m ,
+the
+.Ev MANPATH
+environment variable, the
+.Xr man.conf 5
+configuration file, or the default documented in
+.Xr man.conf 5 .
+.It
+The section number in ascending numerical order.
+.It
+The page name in ascending
+.Xr ascii 7
+alphabetical order, case-insensitive.
+.El
+.Pp
+Each output line is formatted as
 .Pp
 .D1 name[, name...](sec) \- description
 .Pp
diff --git a/man.1 b/man.1
index 67b53d70..116c6dde 100644
--- a/man.1
+++ b/man.1
@@ -1,9 +1,9 @@
-.\"	$Id: man.1,v 1.21 2017/01/31 19:44:04 schwarze Exp $
+.\"	$Id: man.1,v 1.22 2017/03/17 17:24:41 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: January 31 2017 $
+.Dd $Mdocdate: March 17 2017 $
 .Dt MAN 1
 .Os
 .Sh NAME
@@ -234,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