A plea or sanity in port options menu

[Gonzalo Nemmi]

On Monday 02 February 2009 6:39:25 pm Bill Moran wrote:
> In response to Warren Block <wblock at wonkity.com>:
> > On Mon, 2 Feb 2009, Bill Moran wrote:
> > > How about:
> > >
> > >       Options for port-fu
> > > [ ] BRG   Bernstein Riggs Guillotine parsing
> > > [X] QFZ   Quantum Freeze Zulu rending
> > >
> > > At least that one gives me _some_ idea what those TLAs mean.
> >
> > There was talk some time ago of having extended descriptions.  Several
> > ideas, but the one that made the most sense to me would be a box at the
> > bottom that would display a description as you moved through the
> > options:
> >
> > [.] BRG
> > [X] QFZ
> >
> > Bernstein Riggs Guillotine parsing
> >
> > with the . representing the cursor/highlight position.  Move down and
> > the bottom line would change to say "Quantum Freeze Zulu rending".  The
> > nice thing about the box at the bottom is it would give a full line or
> > possibly several lines for explanations.
> >
> > Seems like it could be added without breaking the existing system with
> > an optional OPTIONS_DESC variable that would correspond with OPTIONS.
> > I don't really know how hard that would be; ideas are cheap,
> > implementation more costly.
>
> I don't think there's any need for any new features in the ports
> infrastructure.  I think it's just a matter of Makefile authors taking
> the time to describe their options.  A quick test of some ports turns
> up this one:
>
>  [ ] OPENGL  OpenGL support
>
> True but useless.  How about:
>
>  [ ] OPENGL  Use OpenGL graphics library
>
> ...which, at least give the user _some_ idea what they're doing.
>
> OpenGL probably isn't a good example, however.  It's pretty easy to Google
> OpenGL and figure out what it is.  Here's some more bizarre options:
>
>  [X] EPUB          Epub modules
>  [X] EXTENSIONS    Extensions
>  [X] TEMPLATE      Templates
>  [X] TOOLS         Tools
>
> I mean, if I enable "Extensions", what happens?  How do I figure out
> what happens?  I have to read the Makefile, at which point having these
> options on a menu is pretty pointless.  I mean, I can't even come up
> with a Google search to help me figure out what "tools" are involved
> here.
>
> There are some ports that do this very well.  For example:
>  [ ] NLS               Use internationalized messages
>  [ ] PAM               Build with PAM support (server only)
>  [ ] LDAP              Build with LDAP authentication support
>  [ ] MIT_KRB5          Build with MIT's kerberos support
>  [ ] HEIMDAL_KRB5      Builds with Heimdal kerberos support
>  [ ] OPTIMIZED_CFLAGS  Builds with compiler optimizations (-O3)
>  [X] XML               Build with XML data type (server)
>  [X] TZDATA            Use internal timezone database (server)
>  [ ] DEBUG             Builds with debugging symbols
>  [ ] ICU               Use ICU for unicode collation (server)
>  [ ] INTDATE           Builds with 64-bit date/time type (server)
>
> I mean, a Google on ICU is liable to bring up all sorts of medical drama
> websites, but I can do a search for "ICU unicode" and find my answer on
> the first result.  Not only am I told that optimized compiler flags are
> an option, but I'm told the exact one that will be used (-O3)
>
> The porters handbook doesn't seem to offer any helpful advice on these:
> http://www.freebsd.org/doc/en/books/porters-handbook/makefile-options.html
>
> In fact, the examples it provides are excellent examples of doing it
> WRONG.
>
> Let me see about making a patch to the porters handbook to provide some
> advice ...

+1,000,000 on your idea.

Yes .. you are absolutely right ... even if you know your way around make && 
gcc && compiling software .. and even if you _really_ know your way around 
make && gcc && compiling software, there's no chance on earth that anyone can 
tell what does every single option on every single Makefile actually mean.

As you pointed out:

[ ] BRG
[X] QFZ

means _nothing_ to 99.9% of the users... Be Really Grumpy? Buy Red Goggles? 
Quite Faster Zapping?? Quit Filtering Zealots??

This kind of things really hurts the "good documentation" reputation that 
FreeBSD has rightfully earned.

And I do agree with you:

" I don't think there's any need for any new features in the ports 
infrastructure.  I think it's just a matter of Makefile authors taking the 
time to describe their options. "

And once again .. this is the way to go for me too:

> There are some ports that do this very well.  For example:
>  [ ] NLS               Use internationalized messages
>  [ ] PAM               Build with PAM support (server only)
>  [ ] LDAP              Build with LDAP authentication support
>  [ ] MIT_KRB5          Build with MIT's kerberos support
>  [ ] HEIMDAL_KRB5      Builds with Heimdal kerberos support
>  [ ] OPTIMIZED_CFLAGS  Builds with compiler optimizations (-O3)
>  [X] XML               Build with XML data type (server)
>  [X] TZDATA            Use internal timezone database (server)
>  [ ] DEBUG             Builds with debugging symbols
>  [ ] ICU               Use ICU for unicode collation (server)
>  [ ] INTDATE           Builds with 64-bit date/time type (server)

no need to break anything ... just _be_verbose_

Regards
-- 
Blessings
Gonzalo Nemmi