freeciv 2.6.4: port info doesn't explain the list of executable programs

[JDLH (Jim DeLaHunt)]

The freeciv and freeciv-x11 ports install a number of executable programs and three man pages. But none of the information MacPorts supplies names those programs. Thus it's hard to figure out how to use freeciv once it is installed.

Executable programs installed by freeciv port: freeciv-sdl2 (or freeciv-sdl on older OSs), freeciv-mp-cli .

Executable programs installed by freeciv-x11 port: freeciv-gtk2, freeciv-mp-gtk2 .

Executable programs installed by both ports: freeciv-manual, freeciv-server .

Man pages installed by both ports: 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 .

The most fundamental thing to tell users is: for the freeciv port, run freeciv-sdl2 or freeciv-sdl; for the freeciv-x11 port, run freeciv-gtk2.

I can think of two ways to include this information:

1. Add several more lines with this information to the long_description string in the Portfile.

2. Create a new man file freeciv which explains how MacPorts has installed all the various parts, and how to find them.

Which is the better approach? I'm willing to submit a patched Portfile.

[ryandesign (Ryan Carsten Schmidt)]

Users are expected to run e.g. port contents freeciv to find out what a port has installed.

[JDLH (Jim DeLaHunt)]

I see the logic of that. I guess MacPorts is fundamentally about porting the upstream content, not reauthoring it.

But in the case of freeciv, the MacPorts ports pick and choose what to bring along from upstream. Just two clients of the six or so on offer. Some but not all of the ancillary tools. It would be nice if MacPorts would at least allude to that in the "port info" output.

Freeciv can't be the only port in this situation. Are there other ports which install many components, or a very different subset than the upstream project installs? How do those ports communicate to the user about what MacPorts does?

Freeciv could document better. They could create a manpage "freeciv", so that "man freeciv" would introduce the user to the variety of clients and ancillary tools. I can take this up with the freeciv project upstream.

Would it be reasonable to at least add a sentence to the long_description saying something like, "Run 'man freeciv-client' for more information."?

[jmroot (Joshua Root)]

Quick-start instructions can go in a port's notes.

[ryandesign (Ryan Carsten Schmidt)]

Replying to JDLH:

Are there other ports which install many components, or a very different subset than the upstream project installs? How do those ports communicate to the user about what MacPorts does?

In some cases, ports need to diverge from upstream's default installation layout, for any number of reasons. Sometime's upstream's default installation layout is not appropriate in MacPorts. Sometimes upstream provides no installation method at all and we have to invent one. I don't have data about what proportion of ports do this.

In most cases, ports do not communicate to the user. The user finds ports by name or by searching, installs a port, reads any notes the port prints, and uses port contents to figure out what was installed.

Would it be reasonable to at least add a sentence to the long_description saying something like, "Run 'man freeciv-client' for more information."?

I would not add such information to the description because it seems redundant. Yes, users can consult manpages, but users should already be accustomed to using port contents to discover what manpages, info pages, or other documentation were installed.

Replying to jmroot:

Quick-start instructions can go in a port's notes.

Yes they can, but it should be remembered that notes are printed not only after first installation but also after every port upgrade. Information that is only useful for initial setup quickly becomes spam. If we put too much spam in notes, it trains users to ignore notes.

[JDLH (Jim DeLaHunt)]

Thank you everyone for the discussion. I see that explaining a port is complicated. One can argue that the MacPorts port should explain better, and one can argue that the upstream projects should explain better.

Ryan makes a good point:

In most cases, ports do not communicate to the user. The user finds ports by name or by searching, installs a port, reads any notes the port prints, and uses port contents to figure out what was installed.

Fair enough. But does MacPorts tell users that is what they should do? I have been fumbling my way around MacPorts for a long time, but I have not learned to include port contents in my workflow.

The MacPorts Guide has a section "Common Tasks" ​https://guide.macports.org/#using.common-tasks . I don't see "Install a port" in that section. It would be helpful to have an "Install a port" section. It might say something like, use sudo port install to install the port, then here are some common problems that can occur, then use port contents to find out what the port actually installed.

If I were to draft such a section, would that be welcome?

Returning to the freeciv port, one of the most severe problems for me was choosing between the freeciv and the conflicting freeciv-x11 subport. The long_description paragraph seems to be the best place to describe this. Port notes don't appear until after the user has chosen between main port and incompatible sub-port.

I will point out that the documentation for the long_description keyword (​https://guide.macports.org/#reference.keywords) has an example listing what programs the port provides:

long_description    foobar provides the following programs: \
                    \n \
                    \n* foo, a lorem ipsum utility \
                    \n* bar, a high-performance amet consectetur \
                    \n* baz, an eiusmod tempor converter

I still think it would be an improvement to add a couple of sentences to the long_description, saying that freeciv installs the mac-Native freeciv-sdl2 client, while the freeciv-x11 subport installs the X11 freeciv-gtk2 client, and they can't both be installed. I would be fine with cutting out half of the existing flowery description text, which is mostly a blurb for how wonderful the game is.

(And by the way, I know from building freeciv from source myself that the two clients, and more, can in fact coexist. But offering all that through MacPorts is a matter for a different enhancement request.)