Date: Sat, 6 Oct 2012 09:32:31 -0400 From: Eitan Adler <lists@eitanadler.com> To: Doug Hardie <bc979@lafn.org> Cc: FreeBSD-PORTS <freebsd-ports@freebsd.org> Subject: Re: New Port Options Message-ID: <CAF6rxgkbrO0pgvgu4g1-iJjxwWeO_8W5y0aX7=1cK_ioAxMjUA@mail.gmail.com> In-Reply-To: <6B7F31C1-0A5C-4B65-AC5B-BCCE21817692@lafn.org> References: <6B7F31C1-0A5C-4B65-AC5B-BCCE21817692@lafn.org>
next in thread | previous in thread | raw e-mail | index | archive | help
On 6 October 2012 01:01, Doug Hardie <bc979@lafn.org> 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 th=
ings 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 provid=
es. However, it does presume that you know a few things about the port str=
ucture that are probably common knowledge to anyone involved with it, but n=
ot to those of us who just "use" it. The first update I made to the Makefi=
le cause a slew of make errors that were pretty much useless. They meant n=
othing to me. My first thought was that somehow I had munged one of the in=
cludes 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 read=
ing the handbook, I noticed that in the PORT_OPTIONS clause you have to pre=
cede the option name with a M. That is not at all obvious and is easily mi=
ssed. 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' opti=
on:
:Mpattern Select only those words that match the rest of the modifie=
r.
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 selecte=
d is completely different from that for an option that is not selected. Th=
at is just weird. The use of {} for one and () for the other again must ha=
ve some reason other than it just won't work otherwise. No clue is given i=
n 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 reg=
ular diff. My recollection is that the last time a unified diff was reques=
ted 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 bee=
n 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 :)
--=20
Eitan Adler
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?CAF6rxgkbrO0pgvgu4g1-iJjxwWeO_8W5y0aX7=1cK_ioAxMjUA>