[MacPorts] #62793: freeciv 2.6.4: port info doesn't explain the list of executable programs

[MacPorts]

#62793: freeciv 2.6.4: port info doesn't explain the list of executable programs
--------------------------+--------------------
  Reporter:  JDLH         |      Owner:  (none)
      Type:  enhancement  |     Status:  new
  Priority:  Low          |  Milestone:
 Component:  ports        |    Version:  2.6.4
Resolution:               |   Keywords:
      Port:  freeciv      |
--------------------------+--------------------

Comment (by JDLH):

 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.)

-- 
Ticket URL: <https://trac.macports.org/ticket/62793#comment:5>
MacPorts <https://www.macports.org/>
Ports system for macOS