port notes

[Ryan Schmidt]

On May 1, 2010, at 15:34, Scott Haneda wrote:

> Do you recall the history on "notes" and its behavior,

I vaguely recall that we were using ui_msg a lot in ports which was getting a little obtuse, and notes was designed as a cleaner interface, and also to let people see a port's notes without having to install, or reinstall, a port.


> I am wondering why its use is not more of a mimic of ui_msg.  Maybe us_msg could have just mapped out to notes, so that `port notes` would simply present the ui_msg to the user regardless of it being in the middle of installing or not.

I don't think that makes sense. ui_msg and notes really aren't very related. Really, we were abusing ui_msg before. ui_msg is a normal command that is frequently used inside phases, inside conditional statements, etc., merged in with other code that actually does compiling or installation. How would you propose MacPorts should wade through all that to find just the relevant messages?

notes is meant to be like description and long_description, just a block of text describing how to use the port, that isn't conditional on anything. This is partly why I've had trouble switching to using it in some of my existing ports.


> I am trying to understand when to use notes, and when to use ui_msg, but not entirely seeing a very strong reason to use ui_msg any longer, now that notes is available.  However, notes is a little more cumbersome to use, and the presentation of it is not as nice as ui_msg in the actual tcl.
> 
>    set my_notes Here are some notes.
>    append my_notes Here are some more notes.
>    notes ${my_notes}
> 
> versus...
> 
>    ui_msg "Here are some notes."	
>    ui_msg "Here are some more notes."
> 
> 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.

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

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.

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.

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.

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.