#42265: Man pages missing links (broken .UR, .UE requests)
Open Date: 2021-05-13 19:01
Last Update: 2021-09-19 18:59
URL for this Ticket:
https://osdn.net//projects/freeciv/ticket/42265
RSS feed for this Ticket:
https://osdn.net/ticket/ticket_rss.php?group_id=12505&tid=42265
---------------------------------------------------------------------
Last Changes/Comment on this Ticket:
2021-09-19 18:59 Updated by: jdlh
Comment:
@cazfi, Thank you for the report of these links on Debian.
Back in June 2021 I posted on the forums, http://forum.freeciv.org/f/viewtopic.php?t=91957 Do you see links in the man pages?, asking if anyone else could report on how these man pages worked on Windows and Linux systems. As of 19 Sept 2021, there are no replies.
---------------------------------------------------------------------
Ticket Status:
Reporter: jdlh
Owner: (None)
Type: Bugs
Status: Open
Priority: 5 - Medium
MileStone: (None)
Component: Documentation
Severity: 5 - Medium
Resolution: None
---------------------------------------------------------------------
Ticket details:
In the man pages freeciv-client(6), freeciv-server(6), and freeciv-modpack(6), there are sections "Bugs" and "More Info", which are supposed to contain hyperlinks to https://osdn.net/projects/freeciv/ticket/ and http://www.freeciv.org/. Instead, those URLs are missing. I think the reason is that these parts of the man pages use .UR and .UE requests, and the man tools (on my system at least) are dropping those requests from the formatted output.
To Reproduce
From the command line, type man freeciv-client or man freeciv-server or man freeciv-modpack.
Look at the "Bugs" and "More Info" sections.
Observed behaviour
Sentences end abruptly, with the link text, a space then a period:
BUGS
Please report bugs to the Freeciv bug tracker .
MORE INFO
See the Freeciv homepage .
Expected behaviour
Sentences include both link text and URL in some form, e.g.:
BUGS
Please report bugs to the Freeciv bug tracker <https://osdn.net/projects/freeciv/ticket/>.
MORE INFO
See the Freeciv homepage <http://www.freeciv.org/>.
Discussion
Observed on Freeciv branches S2_6, S3_0, S3_1, and master.
Observed on macOS 10.13.6 High Sierra.
Using the system supplied man formatter, /usr/bin/man, version 1.6c.
The man page source as installed by Freeciv contains the .UR/.UE requests. Thus it is the user's man page formatter, not Freeciv, which is failing to honour these URL requests. Do typical man page formatters on Linux and Windows display these URLs? If so, this is a Mac-specific problem.
I don't see an easy way past this problem by upgrading user man software. On macOS, installing a better formatter, man-db, did not solve the problem for me. Thus, the most robust solution I can think of is to stop using the .UR and .UE requests in the man page source files. Include the URL link (more precisely, the @BUG_URL@ and @WIKI_URL@ macros) in the body of the page, and leave out the .UR and .UE .
--
Ticket information of Freeciv project
Freeciv Project is hosted on OSDN
Project URL: https://osdn.net/projects/freeciv/
OSDN: https://osdn.net
URL for this Ticket:
https://osdn.net/projects/freeciv/ticket/42265
RSS feed for this Ticket:
https://osdn.net/ticket/ticket_rss.php?group_id=12505&tid=42265