./options-descr file suggestion for ports

[David Southwell]

On Saturday 09 June 2007 13:33:17 you wrote:
> On Sat, Jun 09, 2007 at 09:36:51AM -0700, David Southwell wrote:
> > Hi
> >
> > Would it be possible , when a port has options,  to ask porters if they
> > would consider the merits/demerits of adding:
> >
> > 1. An ./options-descr file in the port directory that describes  the
> > options, their purpose and any notes about an option
> >
> > Reasons:
> > This would be extremely useful for anyone not familiar with the port to
> > help in the task of choosing which options to install.
> >
> > I realise that this would depend upon whether maintainers are willing to
> > add an additional task to the already heavy burden they undertake.
> > Maintainers who are willing to consider this idea but are reluctant to
> > prepare the notes themselves but do not have the time or are for any
> > reason reluctant to do so, could invite users to submit notes for
> > incorporating in ./options-descr.
> >
> > By way of example I am just installing www/ruby-gem-rails and had no
> > immediate idea whether or not to add fastcgi support without trying to
> > find out whether it is or is not needed when one has mod_ruby installed
> > and
> > LoadModule ruby_module libexec/apache/mod_ruby.so
> > in httpd.conf. A brief note in a ./options-descr could be very helpful,
> > especially for some ports where the options are sometimes numerous and
> > not always completely documented.
> >
> > A little bit of intial guidance about options would be most helpful to a
> > system administrator who is not necessarily familiar with the a specific
> > port.
>
> That's what ports/KNOBS supposed to be, see rev. 1.1 by ahze:
>
> Limitations to KNOBS: In the future we plan to add support for
> OPTIONS to support the KNOBS file, and so dialog(1) will be able to
> handle the size of each knob knob-name's are limited to 12
> characters and knob-descriptions are limited to 45 characters, not
> including the white space between the knob-name and
> knob-description.
>
> Though, I don't know when OPTIONS support to KNOBS will be added.
>
> -Kirill

Interesting I had forgotten about KNOBS mainly because I do not really feel it 
answers the contextural need. I was proposing something far more freeform 
than than the KNOBS idea. 45 chars does not permit the inclusion of 
qualitative information and guidance in contrast to the rather terse forms of 
documentation that are of limited value to those near the bottom of the 
learning curve.

That is why I am suggesting a separate file to contain as much or as little 
information as experienced users might care to provide about the options for 
a particular port. 

I may be looking a bit far into the future but I could see such a file being  
thought of as a component for what might, in the long term, contribute to the 
building  of a ports users wiki.

My two pennorth

David