Document variant description in guide

[markd at macports.org]

>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".

Well it took awhile, but here's my best shot at this.  Very good
suggestions.  Revisions are in r35548.

Mark