[PATCH] man/man7/man.7: Don't warn if groff_man.7 is not installed

[PATCH] man/man7/man.7: Don't warn if groff_man.7 is not installed

[Ash Holland]

When I invoke e.g. `man man`, I see a warning:

    /home/ash/.nix-profile/bin/man: can't resolve man7/groff_man.7

This is observed by others too: <https://askubuntu.com/q/1521258/478436>

To avoid this, we can simply ask troff not to emit this message:
<https://www.gnu.org/software/groff/manual/groff.html#index-_002esoquiet>

Signed-off-by: Ash Holland <x-hv2j5m@keysmash.solutions>
---
 man/man7/man.7 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/man/man7/man.7 b/man/man7/man.7
index f460f4ad3..cdf019063 100644
--- a/man/man7/man.7
+++ b/man/man7/man.7
@@ -1 +1 @@
-.so man7/groff_man.7
+.soquiet man7/groff_man.7
-- 
2.51.2

Re: [PATCH] man/man7/man.7: Don't warn if groff_man.7 is not installed

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 1339 bytes --]

Hi Ash,

At 2025-12-09T21:38:00+0000, Ash Holland wrote:
> When I invoke e.g. `man man`, I see a warning:
> 
>     /home/ash/.nix-profile/bin/man: can't resolve man7/groff_man.7
> 
> This is observed by others too: <https://askubuntu.com/q/1521258/478436>
> 
> To avoid this, we can simply ask troff not to emit this message:
> <https://www.gnu.org/software/groff/manual/groff.html#index-_002esoquiet>

I'm the GNU maintainer of groff and the author (instigator?) of the
`soquiet` request.  Your patch isn't wrong, but I must point out that
the `soquiet` request is new to groff 1.23.0 (which isn't that new
anymore--it was released in July 2023).

> -.so man7/groff_man.7
> +.soquiet man7/groff_man.7

If Alex applies this, it means the page redirection[1] will stop working
_where it had been before_ for any systems using groff 1.22.4 or older.

If Alex wants to make the Linux man-pages require groff 1.23.0 or later
(there's been no subsequent release, but I'm working on it[2]), that's
fine with me, but such a decision should be announced so that
distributors of man-pages packages can judge whether they need/want to
increment the versioning of their package dependencies accordingly.

Regards,
Branden

[1] that's not really what it is, but let's pretend
[2] https://savannah.gnu.org/bugs/?65099

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH] man/man7/man.7: Don't warn if groff_man.7 is not installed

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 3732 bytes --]

[CC += Collin]

Hi Ash, Branden, Collin,

On Tue, Dec 09, 2025 at 03:51:49PM -0600, G. Branden Robinson wrote:
> Hi Ash,
> 
> At 2025-12-09T21:38:00+0000, Ash Holland wrote:
> > When I invoke e.g. `man man`, I see a warning:
> > 
> >     /home/ash/.nix-profile/bin/man: can't resolve man7/groff_man.7
> > 
> > This is observed by others too: <https://askubuntu.com/q/1521258/478436>

Interesting:

	alx@devuan:~$ man man
	man: can't resolve man7/groff_man.7
	alx@devuan:~$ man -w man
	man: can't resolve man7/groff_man.7
	/usr/share/man/man1/man.1.gz
	alx@devuan:~$ man -aw man
	man: can't resolve man7/groff_man.7
	/usr/share/man/man1/man.1.gz
	/usr/share/man/man1/man.1posix.gz
	/usr/share/man/man7/groff_man.7.gz
	alx@devuan:~$ man -aw groff_man
	/usr/share/man/man7/groff_man.7.gz
	alx@devuan:~$ man 7 man | head -n1
	man: can't resolve man7/groff_man.7
	groff_man(7)            Miscellaneous Information Manual           groff_man(7)

Why does man(1) resolve the .so directives for listing files?  Shouldn't
it just list the file I asked for?  If the file is a .so page, I want to
see the file that contains the .so, and not the file it sources.  It's
my problem to follow the .so link later myself, I think.

That would remove the diagnostic when reading man(1), because unless you
try to read the page man(7), there's no reason why man(1) would even try
to resolve it.

I'd qualify this as a bug (or at least dubious feature) of man-db.

mandoc's man(1) doesn't have this bug:

	alx@devuan:~$ mman -aw man
	mman: outdated mandoc.db lacks man(1) entry, run makewhatis /usr/share/man
	mman: outdated mandoc.db lacks man(7) entry, run makewhatis /usr/share/man
	mman: outdated mandoc.db lacks man(7) entry, run makewhatis /usr/local/share/man
	/usr/share/man/man1/man.1.gz
	/usr/share/man/man1/man.1posix.gz
	/usr/share/man/man7/man.7.gz
	/usr/local/share/man/man7/man.7

> > 
> > To avoid this, we can simply ask troff not to emit this message:
> > <https://www.gnu.org/software/groff/manual/groff.html#index-_002esoquiet>
> 
> I'm the GNU maintainer of groff and the author (instigator?) of the
> `soquiet` request.  Your patch isn't wrong, but I must point out that
> the `soquiet` request is new to groff 1.23.0 (which isn't that new
> anymore--it was released in July 2023).
> 
> > -.so man7/groff_man.7
> > +.soquiet man7/groff_man.7

I'm not yet convinced that this is beneficial.  I'd like to first hear
Collin's opinion of my proposal of not following .so in man(1)
unnecessaily.

> If Alex applies this, it means the page redirection[1] will stop working
> _where it had been before_ for any systems using groff 1.22.4 or older.

Would it be possible to implement a .soquiet fallback as you did with
.MR in Debian?

> If Alex wants to make the Linux man-pages require groff 1.23.0 or later
> (there's been no subsequent release, but I'm working on it[2]), that's
> fine with me, but such a decision should be announced so that
> distributors of man-pages packages can judge whether they need/want to
> increment the versioning of their package dependencies accordingly.

Actually, this will happen sooner or later, and the exact date depends
more on you than me.  MR.sed is coming eventually.  :)

I'd prefer if Ingo would release a new version of mandoc(1) before that
happens, but I'm not going to wait forever.  He told me he might release
around the end of 2025 or begining of 2026, but that it wasn't certain.
We'll see.


Have a lovely night!
Alex

> Regards,
> Branden
> 
> [1] that's not really what it is, but let's pretend
> [2] https://savannah.gnu.org/bugs/?65099

-- 
<https://www.alejandro-colomar.es>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH] man/man7/man.7: Don't warn if groff_man.7 is not installed

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 4741 bytes --]

[looping in groff list due to musings on its development]

Hi Alex,

At 2025-12-10T00:18:32+0100, Alejandro Colomar wrote:
> On Tue, Dec 09, 2025 at 03:51:49PM -0600, G. Branden Robinson wrote:
> > I'm the GNU maintainer of groff and the author (instigator?) of the
> > `soquiet` request.  Your patch isn't wrong, but I must point out
> > that the `soquiet` request is new to groff 1.23.0 (which isn't that
> > new anymore--it was released in July 2023).
> > 
> > > -.so man7/groff_man.7
> > > +.soquiet man7/groff_man.7
> 
> I'm not yet convinced that this is beneficial.  I'd like to first hear
> [Colin]'s opinion of my proposal of not following .so in man(1)
> unnecessaily.

Colin with one ell.  Watson != Funk.  :)

> > If Alex applies this, it means the page redirection[1] will stop
> > working _where it had been before_ for any systems using groff
> > 1.22.4 or older.
> 
> Would it be possible to implement a .soquiet fallback as you did with
> .MR in Debian?

Yes, but it would be ugly, because it would require bitwise arithmetic
on the value of the `.warn` register, to temporarily mask off the
position in this bit vector that enables warnings in category "file".
Since the *roff language doesn't have bitwise arithmetic operators, this
means manipulating large, mysterious integers.

https://www.gnu.org/software/groff/manual/groff.html.node/Warnings.html#Warnings

I've been taking examples of this sort of bit fiddling _out_ of groff's
corpus.

See, e.g., <https://savannah.gnu.org/bugs/?57583>.

Not long ago, I sketched a design for an extension to GNU troff syntax
for requests like `warn` and `cflags` that would enable greater
expressiveness.[1]  If anyone ever gets around to implementing that, we
could retire the `soquiet` and `msoquiet` requests from the formatter
language, demoting them to "compatibility macros" in some "tmac" file
that would probably be loaded by default for one release, then not.

Because then you could simply say the following (and this is in fact
almost how I'd write `soquiet` as a macro).

.do nr saved-warn \n[.warn]
.do warn -file
.so man7/groff_man.7
.do warn \n[saved-warn]

This is even completely portable to AT&T troff.

(Maybe "compat124.tmac" would be automatically loaded by "troffrc" in
groff 1.25, but not in groff 1.26.  But we'd keep shipping
"compat124.tmac" forever; as a side effect, this scheme would tend to
drive documents in the direction of either (1) keeping pace with
developments in the formatter, (2) declaring their demand for an old
version, or (3) using a "compatible subset of the language", as AT&T
troff documents largely already do when interpreted with GNU troff.)
All seem like sound practices to me, appropriate to different audiences.

Similarly, if we ever get the string iterator I've spent years grumbling
about,[2] a _whole bunch_ of string-related requests could move to such
a "compat" macro package, and a several contemplated new ones could be
implemented in a new auxiliary package, say, "string.tmac".[3]

> > If Alex wants to make the Linux man-pages require groff 1.23.0 or
> > later (there's been no subsequent release, but I'm working on
> > it[2]), that's fine with me, but such a decision should be announced
> > so that distributors of man-pages packages can judge whether they
> > need/want to increment the versioning of their package dependencies
> > accordingly.
> 
> Actually, this will happen sooner or later, and the exact date depends
> more on you than me.

Yup, I've just got to learn how to document my inscrutable sed(1)
incantations to your satisfaction.  ;-)

> MR.sed is coming eventually.  :)

Aye, and I'll be a happy guy when it does.

> I'd prefer if Ingo would release a new version of mandoc(1) before
> that happens, but I'm not going to wait forever.  He told me he might
> release around the end of 2025 or begining of 2026, but that it wasn't
> certain.  We'll see.

Yeah, the landing of groff 1.23.0 in OpenBSD seems to be a bit stuck as
well.  :(

https://github.com/ischwarze/groff-port/commits/1.23/

Part of the problem there is, I suspect, multiple disagreements between
Ingo and me over what constitutes a "regression" in groff.  In my
opinion, he managed, in mandoc(1)'s test suite, to explore the *roff
language aggressively (that's a good thing), to the point that he
discovered undefined behavior.  And also a perhaps under-appreciated
major difference in AT&T troff and GNU troff syntaxes.

Regards,
Branden

[1] https://lists.gnu.org/archive/html/groff/2025-12/msg00007.html
[2] https://savannah.gnu.org/bugs/?62264
[3] https://lists.gnu.org/archive/html/groff/2024-11/msg00044.html

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]