Ticket #42178

Move man page .so requests to first lines, to let compressed man pages work

Open Date: 2021-05-05 09:51 Last Update: 2021-05-15 19:11

Reporter:
Owner:
Type:
Status:
Closed
Component:
MileStone:
Priority:
5 - Medium
Severity:
5 - Medium
Resolution:
Fixed
File:
4

Details

On at least one distribution of Freeciv, MacPorts, some freeciv man pages fail with an error message like, "can't open `man6/freeciv-client.6': No such file or directory". This is because of two choices conflicting: 1) Freeciv authors man pages for the individual clients as stubs which use a .so request to include another man page source file, e.g. freeciv-client.6. 2) MacPorts compresses man pages when it installs them, changing filenames from e.g. freeciv-client.6 to freeciv-client.6.gz. These choices conflict. Freeciv can work around this by moving the .so request to the start of each stub man file.

How to reproduce

  1. Use MacPorts to Install their freeciv or freeciv-x11 ports on a macOS computer.
  2. From a command line, enter 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,

.\" Freeciv - Copyright (C) 1996 - A Kjeldberg, L Gregersen, P Unold
.\"   This program is free software; you can redistribute it and/or modify
…[left out for brevity]…
.\"   GNU General Public License for more details.
.\"
.so man6/freeciv-client.6

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

MacPorts compresses all man pages as it installs them. Thus the filename for freeciv-client becomes man6/freeciv-client.6.gz. Apparently, man cannot recognise the pattern. Instead of appending a .gz extension and finding the freeciv-client file, it fails instead.

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

I tried altering a Freeciv man page by moving its .so request to the first line of the file, and compressed that.

.so man6/freeciv-client.6
.\" Freeciv - Copyright (C) 1996 - A Kjeldberg, L Gregersen, P Unold
.\"   This program is free software; you can redistribute it and/or modify
…[left out for brevity]…
.\"   GNU General Public License for more details.
.\"
man freeciv-gtk2 then succeeded. Thus I propose changing every one of Freeciv's stub man pages in this way.

There is a MacPorts ticket tracking this issue, #62798 ''freeciv 2.6.4: man freeciv-gtk2 etc. "can't open" "No such file or directory" (.so directive and .gz?)''

Ticket History (3/14 Histories)

2021-05-05 09:51 Updated by: jdlh
  • New Ticket "Move man page .so requests to first lines, to let compressed man pages work" created
2021-05-05 10:28 Updated by: cazfi
2021-05-08 10:50 Updated by: cazfi
  • Resolution Update from None to Accepted
2021-05-12 04:23 Updated by: jdlh
Comment

Here are some more precise instructions for reproducing this issue without MacPorts. gzip -9vnf is the command which MacPorts uses to compress the man pages it installs.

To Reproduce:

  1. Run ./configure, defining $prefix to be the directory into which freeciv is installed. In the following instructions, use this path in place of $prefix. (e.g. for me, $prefix is HOME/opt/freeciv-dev/ ).
  2. Do make install. Man pages get installed into $prefix/share/man/man6/freeciv*.6 .
  3. Do man -M $prefix/share/man freeciv-qt (can use any of freeciv-gtk3.22, freeciv-mp-cli, freeciv-mp-gtk3, freeciv-mp-qt, freeciv-qt, freeciv-sdl2). A correct man page appears, for freeciv-client or freeciv-modpack, depending on which keyword you used.
  4. Do gzip -9vnf $prefix/share/man/man6/freeciv*.6
  5. Repeat man -M $prefix/share/man freeciv-qt (or any of the keywords in step 3 above)

Expected behaviour:

  1. A correct man page appears, for freeciv-client or freeciv-modpack, depending on which keyword you used in step 5 above.

Observed behaviour:

  1. An error message appears, similar to:
    <standard input>:14: can't open `man6/freeciv-client.6': No such file or directory
    
    (END)
    
2021-05-12 04:26 Updated by: cazfi
Comment

Can you test if the patches work?

2021-05-12 04:39 Updated by: jdlh
Comment

Reply To cazfi

Can you test if the patches work?

Patch 0055-Make-man-page-links-to-work-on-OSX.patch works for me within the Freeciv build, using the test from comment "2021-05-11 12:23" by jdlh. I'm working on testing within the MacPorts build now.

2021-05-12 04:55 Updated by: jdlh
Comment

Patch 0027-Make-man-page-links-to-work-on-OSX.patch is effective within the MacPorts build environment.

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]

Thank you for making these patches. You were faster than me — I was just starting to figure out how to make patches within the Freeciv build system.

2021-05-12 05:01 Updated by: cazfi
Comment

Reply To jdlh

I was just starting to figure out how to make patches within the Freeciv build system.

Maybe this helps: http://www.freeciv.org/wiki/How_to_Contribute#How_to_create_patch_file_with_Git

(Edited, 2021-05-12 05:01 Updated by: cazfi)
2021-05-12 05:48 Updated by: chippo
Comment

Reply To jdlh

% patch -p1 <…/…/0027-Make-man-page-links-to-work-on-OSX.patch

If you are using git then you can also apply patches with 'git apply blah.patch' It saves you worrying about which exact directory you are in and lining up the -pN appropriately.

2021-05-15 19:11 Updated by: cazfi
  • Status Update from Open to Closed
  • Owner Update from (None) to cazfi
  • Resolution Update from Accepted to Fixed

Edit

You are not logged in. I you are not logged in, your comment will be treated as an anonymous post. » Login