port notes

[Ryan Schmidt]

On May 2, 2010, at 15:08, Scott Haneda wrote:

> On May 1, 2010, at 2:04 PM, Ryan Schmidt wrote:
> 
>> Let's look at some examples.
>> 
>> In minivmac I haven't converted ui_msg to notes because the text advises the user of a prerequisite file, but only if the file isn't already there. I wasn't sure what I should do about this so I did nothing so far.
> 
> In my research of this, I was grepping through the all the port files and found cases of conditional file checks and then using the notes command.  The ui_msg's you are talking about in minivmac seem important to be able to get to without installing or using port edit to see them.  Seems to me a good candidate to keep the conditions as you have them, and just use notes.

I agree; I'll think about how best to do this.


>> Similarly mysql5 prints a message explaining that if you want to run a server, you need to also install mysql5-server -- but again only if you haven't already done so. How this should be handled with notes is unclear to me.
> 
> Yes, that is a tough one.  I know this condition, and I have countless times, installed mysql5 to have to go back and install it as mysql5-server.  In this case, I lean on putting something about that issue where port info would explain it.  It is a tough call to be honest, it does not belong in port info, but how many people are really going to know to use port notes?

If people don't know to use notes, we should educate people to use notes. :)


>> I use a ui_msg in graphviz-oldgui to let you know if you're on Leopard or newer that you may want to use graphviz-gui instead. This message probably doesn't belong in notes; notes is for setup advice, things you have to configure after installing a port, and you don't really have to set up or configure anything to run the GUI, it's just a nice-to-know.
> 
> So maybe notes is better as you said previously, to be thought of like description and long description.  I would then use it right after those locations in the Portfile.
> 
> description 		foo
> long_description	foo bar baz
> notes			Make sure you are installing the right port, are you sure you do not want 'server'?
> 
> That use case makes perfect sense to me.  I only wish the default behavior would be to show those notes with port info.

Maybe, but the way I see it, the description tells you generally what the software does, and the notes tell you specifically how to use it. You only need the notes after you've decided based on the description that the software will be useful to you. So it makes sense to let the user choose which information to display.


>> With new ports I'm trying to get into the habit of using notes, like with xdotool, where it was straightforward. Some of my other ports (lighttpd, sleepwatcher, wget, whois) could easily have their ui_msgs converted to notes too.
> 
> I am doing the same, trying to find the correct times to use notes over ui_msg.  Take port "pureftpd" which is a "replaced_by" Portfile.  `port info pureftpd` is not clear to me at all that I should not be installing that port, and instead, should be following the chain to the correctly named pure-ftpd.  Trying to install it does generate a clear error explaining what to do though.
> 
> Is this perhaps a good candidate for a notes command that explains this in more detail?  I can then see how it would be valuable to have `port info` also show the notes on that command.  But at the same time, I can see that it would also be fine to put it in the long description as well.  Technically, the description for the port pureftpd is not correct, as it is not installing anything at all.  Maybe the description should just say "This port has been replaced by port pure-ftpd",

Maybe. Worrying about notes vs. ui_msg in replaced_by ports is probably not terribly interesting, though, since those ports are destined for deletion before too long anyway.

> or, maybe it should just take you there automatically.  There is a awful lot of data in a replaced_by Portfile, considering it does nothing. In my opinion I would think it only needs "name" and "replaced_by"; any call to it, redirects the user to the correct port.
> 
> There does not seem to be any functional value in showing the user the replaced_by port at all.

I agree the "replaced_by" functionality could still be improved. For example, it should not be necessary in each port using replaced_by to prevent the installation using a pre-configure block; base should do that automatically. It could probably also automatically decide to default to no distfiles in this case.


> Thanks for the dialogue, this has helped me understand a bit more about correct usage.  Still a little confused on some of the edge cases, luckily the small number of ports I am maintaining precludes me from having to deal with this too often.  Thanks again.