long descriptions in OPTIONS

[Scot Hetzel]

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.
- 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.
- Use OPTION_DESC_FOO instead of DESC_FOO (choice 2).
- 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}; \

Scot