port notes

[Scott Haneda]

On May 1, 2010, at 2:04 PM, Ryan Schmidt wrote:

> On May 1, 2010, at 15:34, Scott Haneda wrote:
> 
>> From what I can gather on this, ui_msg for anything that only pertains to the installation as it is happening.  notes for anything that the user may need to get back to and reference again.  So for example, a launchd load command is a nice candidate for notes,
> 
> But you wouldn't actually do that since MacPorts already prints out launchd usage information if the port installs a launchd plist.

Sorry, bad example.

>> as are many of the other setup related messages that are printed out during install.  ui_msg is perfect for something like "${name} has been installed".
> 
> But you wouldn't actually do that since MacPorts already prints out a message when a port has been installed.

Sorry, bad example... Again.

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

> 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?

> 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.  Regardless, I do have a better understanding of how and when to use notes over ui_msg, though it is not entirely clear, for the simple ports I am maintaining, it does not seem to hard to figure out the right thing to do.

> 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", 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.

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.
-- 
Scott * If you contact me off list replace talklists@ with scott@ *