long descriptions in OPTIONS

[Wesley Shields]

On Sat, Apr 26, 2008 at 04:11:06AM -0500, Scot Hetzel wrote:
> On 4/25/08, Wesley Shields <wxs at freebsd.org> wrote:
> > Based upon an idea in an earlier thread on this list[1] I came up with
> >  two ways of adding an extended description to our existing OPTIONS
> >  framework.
> >
> >  1: Extend the OPTIONS to be 4 fields instead of the current 3 fields.
> >  The 4th field would be the long description - providing more detailed
> >  information about what this option does or supports.  In order to
> >  distinguish between a port with 4 OPTIONS without the long description
> >  (12 fields) and a port with 3 OPTIONS with the long description (also 12
> >  fields) the patch requires the port to turn on a knob (OPTIONS_DESC)
> >  when using the long field.  The idea is that over time this will become
> >  the default and can eventually be removed.
> >
> >  2: Leave OPTIONS as is but support a DESC_FOO variable for each OPTION.
> >  This variable would be the long description field, and if it doesn't
> >  exist a default message indicating such would be displayed.
> >
> >  Both of these methods are displayed to the user when '?' or F1 is
> >  pressed during the dialog screen.  In the case of (1) the extra dialog
> >  is only shown if the port supports it.  In the case of (2) the extra
> >  dialog is always available since we have a default message to display.
> >  I suppose a third way would be to use a default message when the knob is
> >  not set for (1), which would probably simplify things slightly.
> >
> 
> Couple of suggestions:
> 
> - OPTION_DESC (choice 1) or DESC_FOO (choice 2) not defined, then use
> field 2 as the long description along with "[NO EXTENDED DESCRIPTION
> DEFINED]" appended.

Done.  Thanks!

> - Remove "Contact the maintainer to fix this" from choice 2, as some
> maintainers may resent being contacted by users to add extended
> descriptions to their ports.

I meant to take that out, sorry.  :)

> - Use OPTION_DESC_FOO instead of DESC_FOO (choice 2).

Kind of a long variable name, but more descriptive.  Done.

> - add support for ${PORTSDIR}/MK/bsd.optiondescription.mk,  This file
> holds a list of standard extended option descriptions, for example:
> 
> _STD_DESC_A4SIZE= "Sets the default paper size used by ${PORTNAME} -
> A4 (210 mm ? 297 mm) or Letter (8? in ? 11 in, 215.9 mm ? 279.4 mm)"
> 
> The following code, should accomplish the above for choice 2:
> 
> LONGDESC=$$(cd ${.CURDIR} && ${MAKE} ${__softMAKEFLAGS} -V OPTION_DESC_$$1); \
> if [ "x$${LONGDESC}" = "x" ] ; then \
>     LONGDESC=$$(cd ${.CURDIR} && ${MAKE} ${__softMAKEFLAGS} -V
> _STD_DESC_$${1}); \
>     if [ "x$${LONGDESC}" = "x" ]; then \
>          LONGDESC="$$2 [NO EXTENDED DESCRIPTION DEFINED]" ; \
>     fi ; \
> fi ; \
> ${ECHO_CMD} $$1: $${LONGDESC} | fmt >> $${TMPOPTIONDESCFILE}; \
> ${ECHO_CMD} >> $${TMPOPTIONDESCFILE}; \

While I'm not opposed to adding standard descriptions somewhere, I don't
think it is really necessary at this point in time.  I'm not familiar
enough with enough options to say what should be in this file.  It
should be fairly easy to implement later on down the road though, once
people are starting to see trends in common OPTIONS descriptions.

Thank you for your input, I'll update the patch and send-pr it
eventually.

-- WXS