Re: Behaviour of .so differs between mandoc and groff

[Colin Watson]

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

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.

> 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.

-- 
Colin Watson (he/him)                              [cjwatson@debian.org]