Introduce a man(1) -l option as an alias for mandoc -a.

Basically, this does the same as man -l in Linux man-db.
The point is that now all functionality of the combined tool
is reachable from the man(1) command name:
apropos = man -k, whatis = man -f, mandoc = man -cl.

Originally suggested by Carsten dot Kunze at arcor dot de,
current maintainer of the Heirloom Documentation Tools.

While here, add various missing information to the usage()
and to the manuals.

4 files changed, 110 insertions, 21 deletions

diff --git a/apropos.1 b/apropos.1
index b08afa38..6affb6c4 100644
--- a/apropos.1
+++ b/apropos.1
@@ -1,4 +1,4 @@
-.\"	$Id: apropos.1,v 1.33 2014/08/22 04:52:55 schwarze Exp $
+.\"	$Id: apropos.1,v 1.34 2014/08/30 18:08:10 schwarze Exp $
 .\"
 .\" Copyright (c) 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv>
 .\" Copyright (c) 2011, 2012, 2014 Ingo Schwarze <schwarze@openbsd.org>
@@ -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: August 22 2014 $
+.Dd $Mdocdate: August 30 2014 $
 .Dt APROPOS 1
 .Os
 .Sh NAME
@@ -24,7 +24,7 @@
 .Nd search manual page databases
 .Sh SYNOPSIS
 .Nm
-.Op Fl acfkw
+.Op Fl acfklVw
 .Op Fl C Ar file
 .Op Fl M Ar path
 .Op Fl m Ar path
@@ -104,16 +104,30 @@ In this mode, macro keys, comparison operators, and logical operators
 are not available.
 This overrides any earlier
 .Fl k
-option.
+and
+.Fl l
+options.
 .It Fl k
 Support the full
 .Ar expression
 syntax.
 This overrides any earlier
 .Fl f
-option.
+and
+.Fl l
+options.
 It is the default for
 .Nm .
+.It Fl l
+An alias for
+.Xr mandoc 1
+.Fl a .
+This overrides any earlier
+.Fl f ,
+.Fl k ,
+and
+.Fl w
+options.
 .It Fl M Ar path
 Use the colon-separated path instead of the default list of paths
 searched for
@@ -143,6 +157,8 @@ By default, pages from all sections are shown.
 See
 .Xr man 1
 for a listing of sections.
+.It Fl V
+Print version and exit.
 .It Fl w
 Instead of showing title lines, show the pathnames of the matching
 manual pages, just like
diff --git a/main.c b/main.c
index e0380e94..9b1f982e 100644
--- a/main.c
+++ b/main.c
@@ -1,4 +1,4 @@
-/*	$Id: main.c,v 1.187 2014/08/23 22:26:06 schwarze Exp $ */
+/*	$Id: main.c,v 1.188 2014/08/30 18:08:10 schwarze Exp $ */
 /*
  * Copyright (c) 2008-2012 Kristaps Dzonsons <kristaps@bsd.lv>
  * Copyright (c) 2010, 2011, 2012, 2014 Ingo Schwarze <schwarze@openbsd.org>
@@ -154,7 +154,7 @@ main(int argc, char *argv[])
 	show_usage = 0;
 	outmode = OUTMODE_DEF;
 
-	while (-1 != (c = getopt(argc, argv, "aC:cfI:ikM:m:O:S:s:T:VW:w"))) {
+	while (-1 != (c = getopt(argc, argv, "aC:cfI:iklM:m:O:S:s:T:VW:w"))) {
 		switch (c) {
 		case 'a':
 			outmode = OUTMODE_ALL;
@@ -189,6 +189,10 @@ main(int argc, char *argv[])
 		case 'k':
 			search.argmode = ARG_EXPR;
 			break;
+		case 'l':
+			search.argmode = ARG_FILE;
+			outmode = OUTMODE_ALL;
+			break;
 		case 'M':
 			defpaths = optarg;
 			break;
@@ -408,22 +412,23 @@ usage(enum argmode argmode)
 
 	switch (argmode) {
 	case ARG_FILE:
-		fputs("usage: mandoc [-V] [-Ios=name] [-mformat]"
-		    " [-Ooption] [-Toutput] [-Wlevel]\n"
+		fputs("usage: mandoc [-acfklV] [-Ios=name] "
+		    "[-mformat] [-Ooption] [-Toutput] [-Wlevel]\n"
 		    "\t      [file ...]\n", stderr);
 		break;
 	case ARG_NAME:
-		fputs("usage: man [-acfhkVw] [-C file] "
+		fputs("usage: man [-acfhklVw] [-C file] "
 		    "[-M path] [-m path] [-S arch] [-s section]\n"
 		    "\t   [section] name ...\n", stderr);
 		break;
 	case ARG_WORD:
-		fputs("usage: whatis [-V] [-C file] [-M path] [-m path] "
-		    "[-S arch] [-s section] name ...\n", stderr);
+		fputs("usage: whatis [-acfklVw] [-C file] "
+		    "[-M path] [-m path] [-O outkey] [-S arch]\n"
+		    "\t      [-s section] name ...\n", stderr);
 		break;
 	case ARG_EXPR:
-		fputs("usage: apropos [-V] [-C file] [-M path] [-m path] "
-		    "[-O outkey] [-S arch]\n"
+		fputs("usage: apropos [-acfklVw] [-C file] "
+		    "[-M path] [-m path] [-O outkey] [-S arch]\n"
 		    "\t       [-s section] expression ...\n", stderr);
 		break;
 	}
diff --git a/man.1 b/man.1
index 6d9f0903..bff2fd5e 100644
--- a/man.1
+++ b/man.1
@@ -1,4 +1,4 @@
-.\"	$Id: man.1,v 1.3 2014/08/21 02:38:24 schwarze Exp $
+.\"	$Id: man.1,v 1.4 2014/08/30 18:08:10 schwarze Exp $
 .\"	$OpenBSD: man.1,v 1.55 2014/04/03 06:15:18 jmc Exp $
 .\"
 .\" Copyright (c) 1989, 1990, 1993
@@ -32,7 +32,7 @@
 .\"
 .\"     @(#)man.1	8.2 (Berkeley) 1/2/94
 .\"
-.Dd $Mdocdate: August 21 2014 $
+.Dd $Mdocdate: August 30 2014 $
 .Dt MAN 1
 .Os
 .Sh NAME
@@ -40,7 +40,7 @@
 .Nd display manual pages
 .Sh SYNOPSIS
 .Nm man
-.Op Fl acfhkw
+.Op Fl acfhklVw
 .Op Fl C Ar file
 .Op Fl M Ar path
 .Op Fl m Ar path
@@ -91,6 +91,11 @@ 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 h
 Display only the
 .Dq SYNOPSIS
@@ -104,6 +109,31 @@ 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
@@ -211,6 +241,8 @@ specifies the possible
 .Ar section
 values, and their search order.
 Additional sections may be specified.
+.It Fl V
+Print version and exit.
 .It Fl w
 List the pathnames of the manual pages which
 .Nm
diff --git a/mandoc.1 b/mandoc.1
index 1ec1a754..dea7d2bd 100644
--- a/mandoc.1
+++ b/mandoc.1
@@ -1,4 +1,4 @@
-.\"	$Id: mandoc.1,v 1.108 2014/08/22 04:52:55 schwarze Exp $
+.\"	$Id: mandoc.1,v 1.109 2014/08/30 18:08:10 schwarze Exp $
 .\"
 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
 .\" Copyright (c) 2012, 2014 Ingo Schwarze <schwarze@openbsd.org>
@@ -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: August 22 2014 $
+.Dd $Mdocdate: August 30 2014 $
 .Dt MANDOC 1
 .Os
 .Sh NAME
@@ -23,7 +23,7 @@
 .Nd format and display UNIX manuals
 .Sh SYNOPSIS
 .Nm mandoc
-.Op Fl acV
+.Op Fl acfklV
 .Sm off
 .Op Fl I Cm os Li = Ar name
 .Sm on
@@ -51,7 +51,7 @@ and produces
 .Fl T Ns Cm ascii
 output.
 .Pp
-The arguments are as follows:
+The options are as follows:
 .Bl -tag -width Ds
 .It Fl a
 If the standard output is a terminal device and
@@ -68,6 +68,14 @@ to paginate them.
 This is the default.
 It can be specified to override
 .Fl a .
+.It Fl f
+A synonym for
+.Xr whatis 1 .
+This overrides any earlier
+.Fl k
+and
+.Fl l
+options.
 .Sm off
 .It Fl I Cm os Li = Ar name
 .Sm on
@@ -77,6 +85,22 @@ for the
 .Xr mdoc 7
 .Sq \&Os
 macro.
+.It Fl k
+A synonym for
+.Xr apropos 1 .
+This overrides any earlier
+.Fl f
+and
+.Fl l
+options.
+.It Fl l
+A synonym for
+.Fl a .
+Also reverts any earlier
+.Fl f
+and
+.Fl k
+options.
 .It Fl m Ns Ar format
 Input format.
 See
@@ -137,6 +161,18 @@ If multiple files are specified,
 .Nm
 will halt with the first failed parse.
 .El
+.Pp
+In
+.Fl f
+and
+.Fl k
+mode,
+.Nm
+also supports the options
+.Fl CMmOSsw
+described in the
+.Xr apropos 1
+manual.
 .Ss Input Formats
 The
 .Nm