Document variant description in guide (was: [31848] trunk/dports)

[Ryan Schmidt]

On Dec 10, 2007, at 00:09, ryandesign at macports.org wrote:

> Log Message:
> -----------
> Remove extra space before and after variant descriptions, because
> this shows through in the output of "`port variants`".

We need to document variant descriptions in the guide. There doesn't  
appear to be much on that now.

It needs to say that all variants should have a description, except  
for platform "variants" and other MacPorts-provided variants (only  
"universal", I guess), for which MacPorts base should be providing  
descriptions (but currently doesn't; we don't need to document that  
but we do need to fix this in base). It should say that the variant  
description should be short but clear, and ideally not merely repeat  
the name of the variant. It should say that the syntax can be either

variant bar description {foo} {...}

or

variant bar description "foo" {...}

but that with "foo" one will need more quoting / escaping than with  
{foo}. (Or maybe there should be a general section of the guide  
describing these two different kinds of strings; then the variant  
description section can just say that the variant description is any  
valid kind of string.) It should say that because the variant  
description is a string, one should take care not to put whitespace  
between the brackets or quotation marks and the beginning and end of  
the variant description, and also to watch whitespace within the  
description. This is in contrast to the port description and  
long_description, which aren't strings in that sense (what are they?)  
and don't have these whitespace constraints.

If we provide recommendations for the wording of the variant  
description, my recommendation would be to write it as a sentence  
fragment, with a capitalized first letter but no trailing  
punctuation, and to think of the variant description as a radio  
button or checkbox label. (Envision a GUI installation mechanism for  
MacPorts in which variants are shown as checkboxes (for variants that  
stand alone) or radio buttons (for a set of variants which are  
mutually exclusive (using the "conflicts" syntax)).) Thus, it would  
be better to write "Build with support for foo" instead of "Builds  
with support for foo"; "Add support for foo" would be better than  
"Adds support for foo".