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
