port mysteries

[James Berry]

On Feb 25, 2007, at 8:25 AM, Kevin Horton wrote:

> On 25 Feb 2007, at 10:43, James Berry wrote:
>
>> As per my earlier email, list is completely trustworthy, but you  
>> need to understand what it does. It just gives you concise  
>> information about the latest version of the port you've specified.  
>> Int his case, by using the installed pseudo-port, you're  
>> specifying the same port many times, and it gives the same same  
>> answer back for each. (The list action completely ignores the  
>> extra meta-information about the port version which is returned by  
>> the installed pseudo-port).
>
> OK.  I understand.  Thanks for the clear explanations.
>
> I made the mistake of assuming that the info in the man page for  
> port was sufficient to understand the output of the various  
> commands.  Clearly it is only a top level summary.  Other than  
> reading the ports sources, or asking on the e-mail list, is there  
> another source of detailed info on the intricacies of the various  
> port commands and options?

You think the terse one-sentence description of list in port(1) is  
insufficient? ;) I would agree.

It says: "List all available ports"

I probably should say something like:

	"For each port given as an argument, displays the latest available  
version of the port. If no arguments are given, lists the latest  
available version of all ports."


> It would seem that some combinations of port commands and pseudo- 
> ports will yield results that differ from what a casual user would  
> expect (e.g. "port list installed", which lists the correct number  
> of installed ports, but shows all at the latest version, rather  
> than the actual version).  Perhaps port should detect such  
> nonsensical commands, and suggest a useful substitution, and/or  
> warn the user that the output may not be what they expect.  E.g.:

With great power comes great responsibility ;) Actually what you  
suggest would be quite hard to code without a separate parse pass  
over the port command. Not that it's a bad suggestion, but just that  
it would be hard to achieve. A port name expression can be made up of  
set operations on port names, pseudo-ports, and grep expressions,  
only the result of which is seen by the "list" action. At the point  
at which the installed pseudo-port name is expanded, there's no  
understanding that it will be passed to the list action. It's hard,  
in other words, to know that the particular combination of action and  
pseudo-port given might produce results you didn't expect, without  
unduly warning users who do understand the results.

Perhaps we've given the user a chainsaw with which to prune their  
roses. The desired tool in your case was "port installed", but you  
ended up with the "port list installed" instead.

I think the best action is to improve the documentation for the list  
action.

James

>
> % port list installed
> <output of "port list installed">
> Note: "port list installed" shows one line for each available  
> version of a port,
> but each line shows the latest version number for that port, rather  
> than the actual
> version number.  "port echo installed" is more likely to yield the  
> result you want.
>
> The note would follow the output, so it would be likely to be seen  
> by the user.
>
> Kevin Horton
> Ottawa, Canada
>
>