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, 103 insertions, 14 deletions

diff --git a/apropos.1 b/apropos.1
index 52489096..cc169da2 100644
--- a/apropos.1
+++ b/apropos.1
@@ -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 5b473292..a628cd86 100644
--- a/main.c
+++ b/main.c
@@ -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 eb7d884b..e9864676 100644
--- a/man.1
+++ b/man.1
@@ -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 157e4bea..495043a2 100644
--- a/mandoc.1
+++ b/mandoc.1
@@ -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