On Dec 10, 2007, at 00:09, ryandesign@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".