[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
