Re: Behaviour of .so differs between mandoc and groff

[G. Branden Robinson]

[dropped the mandoc list; they won't let me post]

At 2023-04-30T13:44:09+0100, Colin Watson wrote:
> On Sun, Apr 30, 2023 at 07:05:55AM -0500, G. Branden Robinson wrote:
> > The latter choice is a better one from a design perspective, in my
> > opinion, because it is more general.  On the other hand, man pages
> > sourcing the text of pages from other sections on the manual seems
> > about as unlikely as a page in /usr/share/man sourcing one in
> > /opt/man, which I dismissed as unworthy of support above.
> 
> It is, however, a real thing that happens.  Examples from a quick
> search on my system:
> 
>   man3/XCompose.3.gz:.so man5/Compose.5
>   man3/queue.3.gz:.so man7/queue.7
>   man3/sigevent.3type.gz:.so man7/system_data_types.7
>   man3/siginfo_t.3type.gz:.so man7/system_data_types.7
>   man3/sigset_t.3type.gz:.so man7/system_data_types.7
>   man3/sigval.3type.gz:.so man7/system_data_types.7
>   man3/stpecpy.3.gz:.so man7/string_copying.7
>   man3/stpecpyx.3.gz:.so man7/string_copying.7
>   man3/ustpcpy.3.gz:.so man7/string_copying.7
>   man3/ustr2stp.3.gz:.so man7/string_copying.7
>   man3/zustr2stp.3.gz:.so man7/string_copying.7
>   man3/zustr2ustp.3.gz:.so man7/string_copying.7
>   man4/console_ioctl.4.gz:.so man2/ioctl_console.2
>   man4/tty_ioctl.4.gz:.so man2/ioctl_tty.2
>   man7/bash-builtins.7.gz:.so man1/bash.1
>   man7/builtins.7.gz:.so man1/bash.1

Ah, once again I ventured a speculation without empirical support.

Burns me every time.

> I haven't exhaustively checked these, but at least some of them seem
> to be internal to a given package.  My approach in man-db, though not
> an especially scientific one, is to make reasonable efforts to support
> observed usage if it isn't obviously unsupportable or entirely
> unreasonable.

I would raise complaints about several of the examples above, but this
isn't the place.

> > In practice, as I understand it, `so` doesn't achieve anything for
> > man pages that can't be done with symbolic links and (importantly) a
> > man page indexer that is symlink-aware.
> 
> It is worth noting that today there are at least some real-world cases
> where it isn't being used as a mere symlink; bash-builtins(7) is one
> such.

True.  That's kind of a dirty trick it pulls, and I now remember having
seen it several years ago when I was trying to contribute to bash
documentation.[1]  The idea of `so`urcing commonly-used boilerplate text
in man pages has occurred to me many times in the past, but I always
discard it as not worth the additional complexity and adoption
challenges.  (For one thing, we'd need some well-known, fixed, and
curated location for those templates, which would not be valid man(7) or
mdoc(7) documents of themselves, to be stored.)

Thanks for the correction.

Regards,
Branden

[1] That led me to quilt, which led me to groff, and I _still_ haven't
    returned from that stack frame...

signature.asc
Description: PGP signature