Re: Behaviour of .so differs between mandoc and groff

[G. Branden Robinson]

At 2023-04-30T09:24:42+1000, Alexis wrote:
> Ping. Does anyone have any thoughts on this? It's a small but
> persistent irritation on my system. :-)

Hi Alexis,

The groff(7) man page is pretty terse about this request.  Our Texinfo
manual says more.

5.33 I/O
========

'gtroff' has several requests for including files:

 -- Request: .so file
 -- Request: .soquiet file
     Replace the 'so' request's control line with the contents of the
     file named by the argument, "sourcing" it.  FILE is sought in the
     directories specified by '-I' command-line option.  If FILE does
     not exist, a warning in category 'file' is produced and the request
     has no further effect.  *Note Warnings::, for information about the
     enablement and suppression of warnings.
[...]
     'soquiet' works the same way, except that no warning diagnostic is
     issued if FILE does not exist.

This leads the reader to wonder what the '-I' option does.

From troff(1):

    -I dir
        Search the directory dir for files (those named on the command
        line; in psbb, so, and soquiet requests; and in “\X'ps:
        import'”, “\X'ps: file'”, and “\X'pdf: pdfpic'” device control
        escape sequences).  -I may be specified more than once; each dir
        is searched in the given order.  To search the current working
        directory before others, add “-I .” at the desired place; it is
        otherwise searched last.  -I works similarly to, and is named
        for, the “include” option of Unix C compilers.

A few questions then arise in the context of man page rendering.

1.  What does the man librarian set the current working directory to
    when launching the formatter?  (For mandoc, this issue still arises
    but is more internal to the implementation.)

2.  What _should_ the man librarian chdir() to before launching the
    formatter?

3.  Should the man librarian pass the formatter some '-I' options to
    help `so` requests in man pages locate the documents they're trying
    to include?

This seems like the sort of thing that should be negotiated to a common
practice.

The problem of multiple directories in the MANPATH arises, but I think
it can be disposed of.  Manual directories are heterogeneous collections
of documents from sundry sources.  It seems unlikely to me that any man
page author can have any expectation of the existence of any
to-be-sourced file that their package/project doesn't itself also
distribute.  And such package/projects seldom, if ever, install man
pages to multiple hierarchies.

With that out of the way, I think the thing to decide is whether a man
page author should assume that the formatter is being run from the
directory in which the page itself is located (so, a "section directory"
like "man1" or "man3"), or from one level up.

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.

Also, users have expectations, predicated on the section number, about
what sort of man page they will see.  It would be rude and confusing for
printf(1) to just ".so printf.3", even if that worked.

Finally, I would not expect mandoc(1) to retain support for `so` at all,
for security reasons, given its situation within OpenBSD culture.  To be
fair, this isn't an imaginary concern.

man1/foo.1:
.so bar.1

man1/bar.1:
.so foo.1

(On the other hand, mandoc(1) doesn't have to rely on the formatter to
detect this cycle and break it; it _is_ the formatter was well as the
librarian.)

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.  Perhaps `so` support was preserved,
and its practice retained, for a long time because at one point in the
1980s I think there was an AT&T/BSD split over symbolic links even being
supported by the kernel.  (And, to be fair, symbolic links are something
of a hack that can make file system operations more painful.  I see from
the nftw() man page that they were still doing so as late as glibc 2.30,
3 years ago.)

Does this help?

Regards,
Branden

signature.asc
Description: PGP signature