NetBSD Problem Report #59625

From www@netbsd.org  Tue Sep  2 14:14:47 2025
Return-Path: <www@netbsd.org>
Received: from mail.netbsd.org (mail.netbsd.org [199.233.217.200])
	(using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)
	 key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256
	 client-signature RSA-PSS (2048 bits) client-digest SHA256)
	(Client CN "mail.NetBSD.org", Issuer "mail.NetBSD.org CA" (not verified))
	by mollari.NetBSD.org (Postfix) with ESMTPS id 270F51A923A
	for <gnats-bugs@gnats.NetBSD.org>; Tue,  2 Sep 2025 14:14:47 +0000 (UTC)
Message-Id: <20250902141445.708361A923E@mollari.NetBSD.org>
Date: Tue,  2 Sep 2025 14:14:45 +0000 (UTC)
From: schwarze@openbsd.org
Reply-To: schwarze@openbsd.org
To: gnats-bugs@NetBSD.org
Subject: [PATCH] usr.bin/man: support -l option
X-Send-Pr-Version: www-1.0

>Number:         59625
>Category:       bin
>Synopsis:       [PATCH] usr.bin/man: support -l option
>Confidential:   no
>Severity:       non-critical
>Priority:       medium
>Responsible:    bin-bug-people
>State:          pending-pullups
>Class:          change-request
>Submitter-Id:   net
>Arrival-Date:   Tue Sep 02 14:15:00 +0000 2025
>Closed-Date:    
>Last-Modified:  Mon Feb 02 19:50:01 +0000 2026
>Originator:     Ingo Schwarze
>Release:        -current  Sep 2 14:13:07 UTC 2025
>Organization:
OpenBSD and mandoc
>Environment:
N/A, missing feature found by reading the documentation and reading
the source code, not by running it
>Description:

While it is generally not advisable to format manual pages at software
build time and manual pages should instead normally be installed
unformatted, in man(7) or mdoc(7) source form, some software packages,
for a variety of reasons, do have a need to format a manual page at
build time, which raises the question which command packages should
use for that purpose if they want their build system to be as portable
as possible.  The traditional way to format a manual page, of course,
is by running the nroff(1) command, but some operating systems (for
example, OpenBSD and some Linux distros using mandoc by default) no
longer install groff(1) by default.  While running mandoc(1) would
work on NetBSD and most other *BSDs, many Linux distros and most
commercial Unixes do not install mandoc by default.

Some software packages run commands like "man ./manpage.1" (notice the
./ in that command), a quirky syntax that was never supported by
traditional Unix nor by any version of the CSRG's BSD.  Because that
syntax has been supported by man-1.5 (formerly often used in Linux)
since at least 1998 and by man-db (nowadays normally used on Linux)
since at least 2001, it is fairly portable (and also supported by
NetBSD and FreeBSD, but no longer by OpenBSD).  This syntax has many
problems: it is ambiguous (some manual page names do contain slashes,
for example about two dozen in NetBSD), it is very confusing because
"man ./manpage.1" and "man manpage.1" have different meaning, which is
highly counter-intuitive, it is arguably too magical and unclear
because it relies too much on guessing what the user may mean rather
than doing what the user says, and it is hard to document.  For
details, see the recent discussion on the man-db mailing list starting
at

https://lists.nongnu.org/archive/html/man-db-devel/2025-08/msg00000.html


In any case, the result of that discussion was that the maintainers of
all widely-used man(1) implementations and all widely-used manual page
formatters agreed that "man ./manpage.1" is an ill-designed syntax -
specifically, Colin Watson (man-db), G. Branden Robinson (groff), and
myself (mandoc).  So using that syntax should not be recommended to
people writing portable build systems.

All three of us also agree that the syntax "man -l manpage.1" that has
been supported by man-db for about two decades and by the mandoc
implementation of man(1) for about one decade is better designed,
unambigous, and is easy and straightforward to document, so we would
like to start recommending that syntax for portable build systems.

Consequently, i think that it would be valuable if the man(1)
implementation of NetBSD, which is also the currently maintained
version of the original BSD man(1), would support -l.  The attached
patch implements and documents it.

If -l support is added, i think support for "man ./manpage.1" should
probably be kept for a few years to ensure a smooth transition.  After
that, a decision can be made to either delete support for "man
./manpage.1" or to keep it for good - either way, that is out of the
scope of this patch.

You are free to use this patch under the license already at the top of
the files man.c and man.1.  If you want to credit the author, that is
Ingo Schwarze <schwarze@openbsd.org>, but i do not insist on being
credited, this is not a particularly large or difficult patch.

>How-To-Repeat:
 $ cd /usr/src/usr.bin/man
 $ man -l man.1
man: unknown option -- l
>Fix:
Hmm, there is no way to submit the patch via this web form, so i'll
submit the patch separately after opening this ticket.

>Release-Note:

>Audit-Trail:
From: Ingo Schwarze <schwarze@usta.de>
To: gnats-bugs@netbsd.org
Cc: schwarze@openbsd.org
Subject: Re: bin/59625
Date: Tue, 2 Sep 2025 16:20:59 +0200

 Index: man.1
 ===================================================================
 RCS file: /cvsroot/src/usr.bin/man/man.1,v
 retrieving revision 1.31
 diff -u -p -r1.31 man.1
 --- man.1	29 Nov 2024 07:55:10 -0000	1.31
 +++ man.1	2 Sep 2025 13:41:34 -0000
 @@ -38,7 +38,7 @@
  .Pq aka Dq Em man pages
  .Sh SYNOPSIS
  .Nm
 -.Oo Fl acw Ns \&| Ns Fl h Oc
 +.Oo Fl aclw Ns \&| Ns Fl h Oc
  .Op Fl C Ar file
  .Op Fl M Ar path
  .Op Fl m Ar path
 @@ -102,6 +102,15 @@ Search man pages for
  .Ar keyword Ns Pq s ,
  in the same manner as
  .Xr apropos 1 .
 +.It Fl l
 +Interpret all arguments as absolute or relative filenames
 +of the manual page files to display.
 +No search is done and the options
 +.Fl M ,
 +.Fl m ,
 +and
 +.Fl S
 +are ignored.
  .It Fl M Ar path
  Override the list of standard directories which
  .Nm
 Index: man.c
 ===================================================================
 RCS file: /cvsroot/src/usr.bin/man/man.c,v
 retrieving revision 1.73
 diff -u -p -r1.73 man.c
 --- man.c	10 May 2022 00:42:00 -0000	1.73
 +++ man.c	2 Sep 2025 13:41:34 -0000
 @@ -84,6 +84,7 @@ struct manstate {
  	int cat;		/* -c: do not use a pager */
  	char *conffile;		/* -C: use alternate config file */
  	int how;		/* -h: show SYNOPSIS only */
 +	int local;		/* -l: interpret arguments as filenames */
  	char *manpath;		/* -M: alternate MANPATH */
  	char *addpath;		/* -m: add these dirs to front of manpath */
  	char *pathsearch;	/* -S: path of man must contain this string */
 @@ -146,7 +147,7 @@ main(int argc, char **argv)
  	/*
  	 * parse command line...
  	 */
 -	while ((ch = getopt(argc, argv, "-aC:cfhkM:m:P:ps:S:w")) != -1)
 +	while ((ch = getopt(argc, argv, "-aC:cfhklM:m:P:ps:S:w")) != -1)
  		switch (ch) {
  		case 'a':
  			m.all = 1;
 @@ -161,6 +162,9 @@ main(int argc, char **argv)
  		case 'h':
  			m.how = 1;
  			break;
 +		case 'l':
 +			m.local = 1;
 +			break;
  		case 'm':
  			m.addpath = optarg;
  			break;
 @@ -585,7 +589,8 @@ manual(char *page, struct manstate *mp, 
  	 * or a relative path explicitly beginning with "./"
  	 * or "../", then interpret it as a file specification.
  	 */
 -	if ((page[0] == '/')
 +	if (mp->local
 +	    || (page[0] == '/')
  	    || (page[0] == '.' && page[1] == '/')
  	    || (page[0] == '.' && page[1] == '.' && page[2] == '/')
  	    ) {

From: "Christos Zoulas" <christos@netbsd.org>
To: gnats-bugs@gnats.NetBSD.org
Cc: 
Subject: PR/59625 CVS commit: src/usr.bin/man
Date: Tue, 2 Sep 2025 12:59:11 -0400

 Module Name:	src
 Committed By:	christos
 Date:		Tue Sep  2 16:59:11 UTC 2025

 Modified Files:
 	src/usr.bin/man: man.1 man.c

 Log Message:
 PR/59625: Ingo Schwarze: Add a new -l flag that specifies to interpret
 arguments as filenames, keeping the current behavior of interpreting
 arguments as filenames if they begin with "/" "./" or "../" for compatibility.
 In the future we can remove that.


 To generate a diff of this commit:
 cvs rdiff -u -r1.31 -r1.32 src/usr.bin/man/man.1
 cvs rdiff -u -r1.73 -r1.74 src/usr.bin/man/man.c

 Please note that diffs are not public domain; they are subject to the
 copyright notices on the relevant files.

State-Changed-From-To: open->needs-pullups
State-Changed-By: dholland@NetBSD.org
State-Changed-When: Tue, 02 Sep 2025 22:56:49 +0000
State-Changed-Why:
Committed; this should get into -11 though


State-Changed-From-To: needs-pullups->pending-pullups
State-Changed-By: riastradh@NetBSD.org
State-Changed-When: Mon, 02 Feb 2026 04:41:02 +0000
State-Changed-Why:
pullup-11 #176 https://releng.netbsd.org/cgi-bin/req-11.cgi?show=176


From: "Martin Husemann" <martin@netbsd.org>
To: gnats-bugs@gnats.NetBSD.org
Cc: 
Subject: PR/59625 CVS commit: [netbsd-11] src/usr.bin/man
Date: Mon, 2 Feb 2026 19:49:42 +0000

 Module Name:	src
 Committed By:	martin
 Date:		Mon Feb  2 19:49:42 UTC 2026

 Modified Files:
 	src/usr.bin/man [netbsd-11]: man.1 man.c

 Log Message:
 Pull up following revision(s) (requested by riastradh in ticket #176):

 	usr.bin/man/man.1: revision 1.32
 	usr.bin/man/man.c: revision 1.74

 PR/59625: Ingo Schwarze: Add a new -l flag that specifies to interpret
 arguments as filenames, keeping the current behavior of interpreting
 arguments as filenames if they begin with "/" "./" or "../" for compatibility.

 In the future we can remove that.


 To generate a diff of this commit:
 cvs rdiff -u -r1.31 -r1.31.2.1 src/usr.bin/man/man.1
 cvs rdiff -u -r1.73 -r1.73.6.1 src/usr.bin/man/man.c

 Please note that diffs are not public domain; they are subject to the
 copyright notices on the relevant files.

>Unformatted:

Home	PR Database Search