git: 61735a4f685b - stable/14 - man: Add -l option

The branch stable/14 has been updated by des:

URL: https://cgit.FreeBSD.org/src/commit/?id=61735a4f685bb1a1d2a787d79e1541ed017a5ca5

commit 61735a4f685bb1a1d2a787d79e1541ed017a5ca5
Author:     Ingo Schwarze <schwarze@usta.de>
AuthorDate: 2025-09-07 20:52:09 +0000
Commit:     Dag-Erling Smørgrav <des@FreeBSD.org>
CommitDate: 2025-09-16 13:05:54 +0000

    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
    
    (cherry picked from commit 14b61b2e931741281d0bfef426e9809f16006504)
---
 usr.bin/man/man.1  | 24 ++++++++++++++++++------
 usr.bin/man/man.sh | 33 ++++++++++++++++++++++++---------
 2 files changed, 42 insertions(+), 15 deletions(-)

diff --git a/usr.bin/man/man.1 b/usr.bin/man/man.1
index 820d6a5b33a9..707677ccce06 100644
--- a/usr.bin/man/man.1
+++ b/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 :
diff --git a/usr.bin/man/man.sh b/usr.bin/man/man.sh
index b1cfc6c41752..fe9c388c0df8 100755
--- a/usr.bin/man/man.sh
+++ b/usr.bin/man/man.sh
@@ -501,13 +501,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"
@@ -516,9 +524,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
@@ -586,7 +597,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 ;;
@@ -598,6 +609,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 ;;
@@ -610,16 +622,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