man: Add -l option

Add a -l option which causes man to interpret all arguments as paths to
open directly rather than man pages to search for in MANPATH.  See the
PR for a detailed rationale.

PR:		289245
MFC after:	1 week
Reviewed by:	ziaee, emaste
Differential Revision:	https://reviews.freebsd.org/D52385

usr.bin/man/man.1

@@ -33,7 +33,7 @@
 .Nd display online manual documentation pages
 .Sh SYNOPSIS
 .Nm
-.Op Fl adho
+.Op Fl adhlo
 .Op Fl t | w
 .Op Fl M Ar manpath
 .Op Fl P Ar pager
@@ -144,6 +144,15 @@ Search names and descriptions of all manual pages for an extended regular
 .Ar expression ,
 emulating basic functionality of
 .Xr apropos 1 .
+.It Fl l
+Interpret all arguments as absolute or relative filename(s)
+of the manual page(s) to display.
+No search is done and the options
+.Fl M ,
+.Fl m ,
+and
+.Fl S
+are ignored.
 .It Fl m Ar arch Ns Op : Ns Ar machine
 Override the default architecture and machine settings allowing lookup of
 other platform specific manual pages.
@@ -269,12 +278,15 @@ will search the following paths when considering section 4 manual pages in
 .Pa /usr/share/man/man4
 .El
 .Ss Displaying Specific Manual Files
-The
+For compatibility reasons,
 .Nm
-utility also supports displaying a specific manual page if passed a path
-to the file as long as it contains a
+will interpret any argument containing at least one
 .Ql /
-character.
+character as an absolute or relative path to a manual page to be
+displayed.
+This heuristic, made redundant by the more widely supported
+.Fl l
+option, is now deprecated and may be removed in future releases.
 .Sh ENVIRONMENT
 The following environment variables affect the execution of
 .Nm :
@@ -398,7 +410,7 @@ manual page:
 .Pp
 Show a manual page in the current working directory:
 .Pp
-.Dl $ man ./man.1
+.Dl $ man -l man.1
 .Pp
 Show the location of manual pages in sections 1 and 8 which contain the word
 .Ql arm :

usr.bin/man/man.sh

@@ -511,13 +511,21 @@ man_display_page_groff() {
 # Usage: man_find_and_display page
 # Search through the manpaths looking for the given page.
 man_find_and_display() {
-	local found_page locpath p path sect
+	local found_page has_slash locpath p path sect
 
 	# Check to see if it's a file. But only if it has a '/' in
-	# the filename.
+	# the filename or if -l was specified.
 	case "$1" in
-	*/*)	if [ -f "$1" -a -r "$1" ]; then
+	*/*)	has_slash=yes
+		;;
+	esac
+	if [ -n "$has_slash" -o -n "$lflag" ]; then
+		if [ -f "$1" -a -r "$1" ]; then
 			decho "Found a usable page, displaying that"
+			if [ -z "$lflag" ]; then
+				echo "Opening a file directly is deprecated," \
+				    "use -l instead." >&2
+			fi
 			unset use_cat
 			manpage="$1"
 			setup_cattool "$manpage"
@@ -531,9 +539,12 @@ man_find_and_display() {
 				man_display_page
 			fi
 			return
+		elif [ -n "$lflag" ]; then
+			echo "Cannot read $1" >&2
+			ret=1
+			return
 		fi
-		;;
-	esac
+	fi
 
 	IFS=:
 	for sect in $MANSECT; do
@@ -601,7 +612,7 @@ man_parse_opts() {
 	local cmd_arg
 
 	OPTIND=1
-	while getopts 'K:M:P:S:adfhkm:op:tw' cmd_arg; do
+	while getopts 'K:M:P:S:adfhklm:op:tw' cmd_arg; do
 		case "${cmd_arg}" in
 		K)	Kflag=Kflag
 			REGEXP=$OPTARG ;;
@@ -613,6 +624,7 @@ man_parse_opts() {
 		f)	fflag=fflag ;;
 		h)	man_usage 0 ;;
 		k)	kflag=kflag ;;
+		l)	lflag=lflag ;;
 		m)	mflag=$OPTARG ;;
 		o)	oflag=oflag ;;
 		p)	MANROFFSEQ=$OPTARG ;;
@@ -625,16 +637,19 @@ man_parse_opts() {
 	shift $(( $OPTIND - 1 ))
 
 	# Check the args for incompatible options.
-
-	case "${Kflag}${fflag}${kflag}${tflag}${wflag}" in
+	case "${Kflag}${fflag}${kflag}${lflag}${tflag}${wflag}" in
 	Kflagfflag*)	echo "Incompatible options: -K and -f"; man_usage ;;
 	Kflag*kflag*)	echo "Incompatible options: -K and -k"; man_usage ;;
+	Kflag*lflag*)	echo "Incompatible options: -K and -l"; man_usage ;;
 	Kflag*tflag)	echo "Incompatible options: -K and -t"; man_usage ;;
 	fflagkflag*)	echo "Incompatible options: -f and -k"; man_usage ;;
+	fflag*lflag*)	echo "Incompatible options: -f and -l"; man_usage ;;
 	fflag*tflag*)	echo "Incompatible options: -f and -t"; man_usage ;;
 	fflag*wflag)	echo "Incompatible options: -f and -w"; man_usage ;;
-	*kflagtflag*)	echo "Incompatible options: -k and -t"; man_usage ;;
+	*kflaglflag*)	echo "Incompatible options: -k and -l"; man_usage ;;
+	*kflag*tflag*)	echo "Incompatible options: -k and -t"; man_usage ;;
 	*kflag*wflag)	echo "Incompatible options: -k and -w"; man_usage ;;
+	*lflag*wflag)	echo "Incompatible options: -l and -w"; man_usage ;;
 	*tflagwflag)	echo "Incompatible options: -t and -w"; man_usage ;;
 	esac