freeciv 2.6.4: man freeciv-gtk2 etc. "can't open" "No such file or directory" (.so directive and .gz?)

[JDLH (Jim DeLaHunt)]

The freeciv and freeciv-x11 ports install both conventional and stub man pages in man6. The stub man pages do not display correctly. I suspect that this may be due to the stub manpages using an .so directive to include another freeciv man page, and MacPorts storing those man pages using .gz compression.

How to reproduce

1. Install freeciv or freeciv-x11 ports
2. man freeciv-gtk2

Observed behaviour

<standard input>:14: can't open `man6/freeciv-client.6': No such file or directory

(END)

Expected behaviour The same page appears as when one commands, man freeciv-client.

Discussion Any of the stub man pages, freeciv-gtk2, freeciv-gtk3.22, freeciv-gtk3, freeciv-mp-cli, freeciv-mp-gtk2, freeciv-mp-gtk3, freeciv-mp-qt, freeciv-qt, freeciv-ruledit, freeciv-sdl, freeciv-sdl2, freeciv-xaw, will fail in a similar way.

All these pages appear to consist only of a few lines of comments, then a troff "include file" directive of the form,

.so man6/freeciv-client.6

The stubs might refer to man6/freeciv-modpack.6 instead, depending on the stub.

I notice that MacPorts installs these man files in compressed form, as /opt/local/share/man/man6/freeciv-client.6.gz and similar.

So I speculate that maybe the groff or whatever is displaying these man pages is not able to translate the .so man6/freeciv-client.6 directive into the require action to find man6/freeciv-client.6.gz and decompress it. If this is correct, then more ports might be affected than just freeciv.

A possible fix might be for MacPorts to install man6/freeciv-client.6 and man6/freeciv-modpack.6 in uncompressed form, as a special case. Is there a way to specify that in the portfile?

[JDLH (Jim DeLaHunt)]

Update: I changed the title to read "man freeciv-gtk2" instead of "man gtk2". The "freeciv-" prefix is important. Sorry.

[JDLH (Jim DeLaHunt)]

Why I think the problem lies with MacPorts and not the upstream code: when I build freeciv outside of Freeports, and install into a private location, the freeciv installer writes uncompressed man page files. For example,

…private…/freeciv/share/man/man6/freeciv-client.6
…private…/freeciv/share/man/man6/freeciv-gtk2.6

When installed this way, then viewing stub man pages, via man -M …private…/freeciv/share/man freeciv-gtk2 displays the contents of man6/freeciv-client.6 as expected.

[kencu (Ken)]

As a special feature, MacPorts automatically compresses all the manpages when destrooting:

​https://github.com/macports/macports-base/blob/d148e62c89c0fee07e202dd64b132e6134e7537e/src/port1.0/portdestroot.tcl#L201

I am not sure (with 10 seconds looking) if this can be turned off somehow, or if there is some established workaround Portfiles use to get around this for these rare occasions where you (apparently) want them uncompressed...

[JDLH (Jim DeLaHunt)]

It appears that there is a convention of sorts to compress man pages. See the man 5 groff-files, section "Compression_of_roff_Files" ​https://www.man7.org/linux/man-pages/man5/groff_filenames.5.html#Compression_of_roff_Files .

There is a utility soelim which can read groff source files, and do the include operation requested by .so. ​https://www.man7.org/linux/man-pages/man1/soelim.1.html . Maybe the freeciv port could run soelim on the affected man pages, before destrooting? Is soelim available as a standard part of MacPorts, or would the groff port need to become a build dependency?

Or even one could make a patch which does the same thing, i.e. replaces that one line of each affected man source file by a copy of the freeciv-client man source file.

if there is some established workaround Portfiles use …

It would be interesting to search through the source code of many ports to find other ports which use .so requests in their manpages. But all that is in the MacPorts ports repository is portfiles, and patches, not the entire source code of each port. Is there some place where all the source code is assembled, that I could do a search on?

[JDLH (Jim DeLaHunt)]

I took a look at the Groff project mailing list archives. This is not the first time the issue of compressed man pages has come up. A thread there went through a lot of the issues I am encountering: "[Groff] [groff/patch] transparent gzip" ​https://lists.gnu.org/archive/html/groff/2002-08/msg00099.html.

A message there alluded to a workaround: "If you look at the source code of man itself, you will find that there is extra provision for file with a single .so in the first line. Just grp for .so anywhere else, you'll encounter problems. Examples are zshall, as well as all the pvm man pages, and a dozen of sporadic ones."

We have ports pvm and zsh. In a quick look, I didn't see any patches to man pages there.

But I did try altering a freeciv man page by moving its .so request to the first line of the file, and compressed that. man freeciv-gtk2 then succeeded.

Thus, I think that a MacPorts response could be that the upstream should change their man pages to put any .so request in the first line of the man page source file. I will file this bug with freeciv.

[JDLH (Jim DeLaHunt)]

Upstream, Freeciv Ticket #42178 Move man page .so requests to first lines, to let compressed man pages work tracks this: ​https://osdn.net/projects/freeciv/ticket/42178 .

[ryandesign (Ryan Carsten Schmidt)]

There is no way to tell MacPorts not to compress manpages.

MacPorts has been compressing manpages since forever ago, so while it is possible other ports are affected by this issue, I suspect it is not common.

I've never heard of soelim before and I don't believe such a thing is part of MacPorts base.

Sounds like the fix is for upstream to make the change you suggested.

[JDLH (Jim DeLaHunt)]

The upstream developers have come up with patches to their manpage sources which move the .so requests to the first line of their respective files. I tested a patch on the freeciv @2.6.4 build directory within MacPorts. It was successful.

My test method:

% sudo port uninstall freeciv
[… output omitted for brevity …]
% sudo port build freeciv
[… output omitted for brevity …]
% cd `port work freeciv`
% patch -p1 <…/…/0027-Make-man-page-links-to-work-on-OSX.patch 
Password:
patching file doc/man/freeciv-gtk2.6
patching file doc/man/freeciv-gtk3.22.6
patching file doc/man/freeciv-gtk3.6
patching file doc/man/freeciv-mp-cli.6
patching file doc/man/freeciv-mp-gtk2.6
patching file doc/man/freeciv-mp-gtk3.6
patching file doc/man/freeciv-mp-qt.6
patching file doc/man/freeciv-qt.6
patching file doc/man/freeciv-sdl2.6
% head -2 doc/man/freeciv-gtk2.6                                                   
.so man6/freeciv-client.6
.\" Freeciv - Copyright (C) 1996 - A Kjeldberg, L Gregersen, P Unold
% cd ~
% sudo port -k install freeciv
% man freeciv-gtk2
[Success]
% man freeciv-mp-cli
[Success]

So I think we don't need to do anything about this ticket within MacPorts. I'll keep an eye on updates to MacPorts. When the successor to Freeciv 2.6.4 is released, I expect that will contain the fix to this ticket.

[JDLH (Jim DeLaHunt)]

Upstream has patched the bug in all four branches of their codebase: S2_6, which gave us the 2.6.4 version that MacPorts distributes, and which will give us the next 2.6.x version; and the version 3.0 beta branch, and the version 3.1 branch, and their master branch.

Upsteam's ticket is now closed/fixed: ​https://osdn.net/projects/freeciv/ticket/42178 .

[JDLH (Jim DeLaHunt)]

I just found out about keyword "upstream", and it suits this ticket perfectly. Added.