On 6 October 2012 01:01, Doug Hardie <[email protected]> wrote:
> I just converted a port over to the new options structure and have a few
> observations. I have not been involved in any of the discussions about the
> structure as I didn't have the time to get involved. However, a couple
> things came to mind during the process:
Thank you very much for this mail. Since the people writing the
documentation are often the people "very involved" it can be hard to
understand what may confuse someone that isn't insane^W^W doesn't work
on ports all the time.
> 1. The Port handbook is actually quite good in the information it provides.
> However, it does presume that you know a few things about the port structure
> that are probably common knowledge to anyone involved with it, but not to
> those of us who just "use" it. The first update I made to the Makefile cause
> a slew of make errors that were pretty much useless. They meant nothing to
> me. My first thought was that somehow I had munged one of the includes and
> managed to include some random file rather than the right one.
make(1) errors can be pretty obtuse at times. It is hard to account
for all the errors here, but is there something specific that would
have helped you?
> My second idea was that I had typed the option names wrong, but that didn't
> seem to fit with the error messages either. After quite a while of reading
> the handbook, I noticed that in the PORT_OPTIONS clause you have to precede
> the option name with a M. That is not at all obvious and is easily missed.
> Why an M is also baffling. I am sure there is a reason other then it just
> won't work otherwise.
make(1) allows processing on variable contents. In particular the 'M' option:
:Mpattern Select only those words that match the rest of the modifier.
The standard shell wildcard characters (`*', `?', and `[]')
may be used. The wildcard characters may be escaped with a
backslash (`\').
This should be made more clear in the handbook.
> 2. The syntax for a conditional expression for an option that is selected is
> completely different from that for an option that is not selected. That is
> just weird. The use of {} for one and () for the other again must have some
> reason other than it just won't work otherwise. No clue is given in the
> handbook.
See bapt@'s comments. That said, it should be made more clear ;)
> 3. The examples are a bit difficult to distinguish between {} and (). I had
> to look quite a few times before I figured that out.
Was this a font issue? Is there something we could do to help? Perhaps
add more spacing?
> 4. The handbook shows for submitting a change to a port the use of a regular
> diff. My recollection is that the last time a unified diff was requested so
> that things like the file names show.
This is likely an oversight. Unified diffs are much preferred. I've
sent in a patch for approval to correct this issue.
> I only maintain one port so the effort to make the changes would have been
> quite minor for additional ports.
As I said above, your perspective is needed when it comes to the
documentation.
> Its really not that big a change from the maintainer's point of view
This is good to know :)
--
Eitan Adler
_______________________________________________
[email protected] mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-ports
To unsubscribe, send any mail to "[email protected]"
