Document whatis(1) -S and -s; leading, trailing, and double colons

in the MANPATH; and the new whatis.index file.
Include some synching to apropos(1) and to the usage() string.
Use some feedback from jmc@.

3 files changed, 63 insertions, 28 deletions

diff --git a/usr.bin/mandoc/apropos.1 b/usr.bin/mandoc/apropos.1
index 016d1d7d1f3..9f7428d7dac 100644
--- a/usr.bin/mandoc/apropos.1
+++ b/usr.bin/mandoc/apropos.1
@@ -1,4 +1,4 @@
-.\"	$Id: apropos.1,v 1.12 2011/12/25 20:15:54 schwarze Exp $
+.\"	$Id: apropos.1,v 1.13 2011/12/26 12:45:58 schwarze Exp $
 .\"
 .\" Copyright (c) 2011 Kristaps Dzonsons <kristaps@bsd.lv>
 .\"
@@ -14,7 +14,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: December 25 2011 $
+.Dd $Mdocdate: December 26 2011 $
 .Dt APROPOS 1
 .Os
 .Sh NAME
@@ -23,8 +23,8 @@
 .Sh SYNOPSIS
 .Nm
 .Op Fl C Ar file
-.Op Fl M Ar manpath
-.Op Fl m Ar manpath
+.Op Fl M Ar path
+.Op Fl m Ar path
 .Op Fl S Ar arch
 .Op Fl s Ar section
 .Ar expression ...
@@ -58,25 +58,31 @@ Specify an alternative configuration
 in
 .Xr man.conf 5
 format.
-.It Fl M Ar manpath
+.It Fl M Ar path
 Use the colon-separated path instead of the default list of paths
 searched for
 .Xr mandocdb 8
 databases.
 Invalid paths, or paths without manual databases, are ignored.
-.It Fl m Ar manpath
+.It Fl m Ar path
 Prepend the colon-separated paths to the list of paths searched
 for
 .Xr mandocdb 8
 databases.
 Invalid paths, or paths without manual databases, are ignored.
 .It Fl S Ar arch
-Search only for a particular architecture.
-.It Fl s Ar cat
-Search only for a manual section.
+Restrict the search to pages for the specified
+.Xr machine 1
+architecture.
+.Ar arch
+is case insensitive.
+By default, pages for all architectures are shown.
+.It Fl s Ar section
+Restrict the search to the specified section of the manual.
+By default, pages from all sections are shown.
 See
 .Xr man 1
-for a listing of manual sections.
+for a listing of sections.
 .El
 .Pp
 An
@@ -239,24 +245,24 @@ Text production:
 .It Li \&Dx Ta Dx No version reference
 .El
 .Sh ENVIRONMENT
-.Bl -tag -width Ds
+.Bl -tag -width MANPATH
 .It Ev MANPATH
-Colon-separated paths modifying the default list of paths searched for
-manual databases.
+The standard search path used by
+.Xr man 1
+may be changed by specifying a path in the
+.Ev MANPATH
+environment variable.
 Invalid paths, or paths without manual databases, are ignored.
 Overridden by
 .Fl M .
 If
 .Ev MANPATH
-begins with a
-.Sq \&: ,
-it is appended to the default list;
-else if it ends with
-.Sq \&: ,
-it is prepended to the default list; else if it contains
-.Sq \&:: ,
-the default list is inserted between the colons.
-If none of these conditions are met, it overrides the default list.
+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.
 .El
 .Sh FILES
 .Bl -tag -width "/etc/man.conf" -compact
diff --git a/usr.bin/mandoc/apropos.c b/usr.bin/mandoc/apropos.c
index aab04ac25f3..7a0b18dc915 100644
--- a/usr.bin/mandoc/apropos.c
+++ b/usr.bin/mandoc/apropos.c
@@ -1,4 +1,4 @@
-/*	$Id: apropos.c,v 1.12 2011/12/12 01:59:13 schwarze Exp $ */
+/*	$Id: apropos.c,v 1.13 2011/12/26 12:45:58 schwarze Exp $ */
 /*
  * Copyright (c) 2011 Kristaps Dzonsons <kristaps@bsd.lv>
  * Copyright (c) 2011 Ingo Schwarze <schwarze@openbsd.org>
@@ -144,8 +144,8 @@ usage(void)
 
 	fprintf(stderr, "usage: %s "
 			"[-C file] "
-			"[-M manpath] "
-			"[-m manpath] "
+			"[-M path] "
+			"[-m path] "
 			"[-S arch] "
 			"[-s section] "
 			"expression ...\n",
diff --git a/usr.bin/mandoc/whatis.1 b/usr.bin/mandoc/whatis.1
index ff8e5ee5b60..7d94921a1f1 100644
--- a/usr.bin/mandoc/whatis.1
+++ b/usr.bin/mandoc/whatis.1
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: whatis.1,v 1.1 2011/12/26 10:29:57 schwarze Exp $
+.\"	$OpenBSD: whatis.1,v 1.2 2011/12/26 12:45:58 schwarze Exp $
 .\"
 .\" Copyright (c) 1989, 1990, 1993
 .\"	The Regents of the University of California.  All rights reserved.
@@ -40,6 +40,8 @@
 .Op Fl C Ar file
 .Op Fl M Ar path
 .Op Fl m Ar path
+.Op Fl S Ar arch
+.Op Fl s Ar section
 .Ar command ...
 .Sh DESCRIPTION
 .Nm
@@ -85,20 +87,47 @@ or the directories supplied with the
 option or the
 .Ev MANPATH
 environment variable are searched.
+.It Fl S Ar arch
+Restrict the search to pages for the specified
+.Xr machine 1
+architecture.
+.Ar arch
+is case insensitive.
+By default, pages for all architectures are shown.
+.It Fl s Ar section
+Restrict the search to the specified section of the manual.
+By default, pages from all sections are shown.
+See
+.Xr man 1
+for a listing of sections.
 .El
 .Sh ENVIRONMENT
 .Bl -tag -width MANPATH
 .It Ev MANPATH
 The standard search path used by
 .Xr man 1
-may be overridden by specifying a path in the
+may be changed by specifying a path in the
 .Ev MANPATH
 environment variable.
+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.
 .El
 .Sh FILES
 .Bl -tag -width "/etc/man.conf" -compact
 .It Pa whatis.db
-name of the whatis database
+name of the
+.Xr mandocdb 8
+keyword database
+.It Pa whatis.index
+name of the
+.Xr mandocdb 8
+filename database
 .It Pa /etc/man.conf
 default
 .Xr man 1