Add man page "freeciv"
When I say "presently garbled forms of: 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", I mean that as installed on my computer via MacPorts, those man pages do not display correctly. I suspect this is due to a bug in how MacPorts installs the "man6/freeciv-client.6" file in ".gz" compressed form. I think it is not a problem in freeciv, and not important for this ticket. I am opening a ticket on MacPorts about the garble problem.
Reply To jdlh
At least this can be a referral to the "freeciv-client" page
freeciv-client man-page has "See Also" for freeciv-server, so one can found also it with this simple solution (no need to write separate "main level" page for freeciv). Client is what the user is likely to run in any case.
Client is what the user is likely to run in any case.
Yes, client is what the user is likely to run. But what is the user likely to _type_ when looking for a man page about Freeciv? I think the user will not know to type man freeciv-client. They will instead type man freeciv. This ticket makes the case that the response to that user should not be, "No manual entry for freeciv".
Also note that if we make a stub man6/freeciv.6 page containing .so man6/freeciv-client.6, macOS users getting Freeciv via MacPorts will not see that page at the moment. MacPorts garbles such stub man pages. Thus this ticket makes the case that we should in fact write a separate, although short, "main level" page for freeciv.
We agreed! My point was that 'freeciv' man page can be a link to 'freeciv-client', not that 'freeciv' is not needed.
Thank you. I'm glad that we agree about the value of a helpful response to man freeciv.
By "link to 'freeciv-client'", do you mean a stub man6/freeciv.6 page containing .so man6/freeciv-client.6 ? Because that will fail for mac users installing via MacPorts for now.
I also think there is value to giving an overview of Freeciv, including the clients, the server, the modpack, etc. I may make a pull request proposing a simple overview man page like this.
0002-Create-a-new-man-page-freeciv-fixes-ticket-42138.patch adds a new freeciv(6) man page to Freeciv.
The patch works on the master branch. I have compiled it and viewed it with man. I suspect the patch will work on every other version branch also, because it only affects a doc directory which doesn't differ much, and config files which probably patch cleanly. I will test against branch S2_6 next, because I'd like to see this in the next dot release of Freeciv.
Reply To jdlh
I suspect the patch will work on every other version branch also
The "See Also" list of other man pages need to be adjusted per branch as list of client and modpack installer guis has changed.
Confirmed, I can apply 0002-Create-a-new-man-page-freeciv-fixes-ticket-42138.patch to the S2_6 branch (commit 9cd08cd4cbe3dc201703e3609d42723f69065cca) successfully.
Confirmed, I can apply 0002-Create-a-new-man-page-freeciv-fixes-ticket-42138.patch to the S3_0 branch (commit 36bee08bff816d2d6393d6afd7ebef25d41ffe08) successfully.
Reply To cazfi
Reply To jdlh
I suspect the patch will work on every other version branch also
The "See Also" list of other man pages need to be adjusted per branch as list of client and modpack installer guis has changed.
You are right. Sorry for missing that. I will check, and modify this patch for each of the S2_6, S3_0, and S3_1 branches.
Reply To jdlh
Reply To cazfi
Reply To jdlh
I suspect the patch will work on every other version branch also
The "See Also" list of other man pages need to be adjusted per branch as list of client and modpack installer guis has changed.
You are right. Sorry for missing that. I will check, and modify this patch for each of the S2_6, S3_0, and S3_1 branches.
OK, patches are now posted for each of the branches: master, S2_6, S3_0, and S3_1. Each one had a different set of man pages.
Is there a page with instructions to documentation writers somewhere? Because it might be nice to add to it, "update the See Also section of man page freeciv(6)".
Maybe we should also add, to the "See Also" section of every other full-content man page, an entry "freeciv(6)" to refer back to this new page? That would be a bunch more work for not much benefit. Perhaps it's better to leave that as a note to the next person who updates each full-content man page.
Info for a new contributor: osdn lacks "In review" / "In testing" status, so we misuse "Accepted" to mean that. It doesn't mean that the patch has already passed the review period without complaints. Rather it means that a maintainer has Accepted to handle the patch.
Freeciv incudes many man pages. The most important of them are "freeciv-client", "freeciv-server", and "freeciv-modpack". However, it does not include the manpage which would be most obvious for a new Freeciv user trying to figure things out: "man freeciv".
I suggest adding a man page named "freeciv". At least this can be a referral to the "freeciv-client" page, as the client pages like "freeciv-gtk2" are. An even better role for it would be to introduce the various parts of the Freeciv system. It could also explain interactions between parts, such as the way the client discovers the server in the install location, as explained in ticket #42134 "gtk3.22 client loses connection to server it starts" https://osdn.net/projects/freeciv/ticket/42134 .
It was not at all obvious to me that the man pages I should read to learn about Freeciv were "freeciv-client" and "freeciv-server". "Man freeciv" was what I thought of to try.
By the way, it looks to me like the list of freeciv man pages is: freeciv-client, freeciv-server, freeciv-modpack, freeciv-manual, freeciv-ruledit, and presently garbled forms of: 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 .