Let's add variant descriptions

[Ryan Schmidt]

Oh sure, I agree. I'll just add two words to what you've already  
said: word wrap.

No, wait: I will say more than that. It's annoying that "port search"  
shows description, but "port info" only shows long_description.

And now I will say much more. Let's try another mockup:


$ port info minivmac
minivmac: a Mac 128K, Mac 512K, Mac 512KE, Mac Plus and Mac
	SE emulator
Version 2.8.2, Revision 1
Homepage: http://minivmac.sourceforge.net/

Mini vMac is a Macintosh emulator. It emulates the earliest Macs,
from the original Mac 128K (built 1984-85) to the Mac SE (1987-1990).
The default is to emulate a Mac Plus (1986-1990); this is also the
best-tested and therefore recommended emulation.

To use Mini vMac, you need a ROM file from the type of machine
you're emulating. Mac ROMs are copyrighted by Apple, so you must
extract the ROM from a real physical Mac that you own. Use the
CopyROM program for this, which you can download from the Mini
vMac web site (More > Extras).

Variants:
*	universal: Build a universal binary
	mac128k: Emulate a Macintosh with 128K RAM and 2 drives
	mac512k: Emulate a Macintosh 512K with 512K RAM and 2 drives
	mac512ke: Emulate a Macintosh 512Ke with 512K RAM and 6
		drives
*	macplus: Emulate a Macintosh Plus with 4 MB RAM and 6 drives
	macse: Emulate a Macintosh SE with 4 MB RAM and 6 drives

* Note: These variants will be automatically selected.

Build Dependencies: bart, lisa, maggie
Library Dependencies: marty, doc, clara
Runtime Dependencies: mal, zoe, river

Maintainers: ryandesign at macports.org, comaintainer at example.com


So I changed the first line to be ${name}: ${description}. I don't  
think we need to be so verbose as to say "Name: ${name}" and  
"Description: {description}". If the description is too long for the  
terminal window, it should word wrap and subsequent lines should  
indent. I feel this line should stand out; to do this, we could add a  
blank line after it and/or we could make it ANSI bold (I'd prefer the  
bold). The next line is the version and the revision, if applicable.  
Then I show the homepage. I'm not even sure we need the label  
"Homepage:" but it's not bad if it's there.

I toyed with listing the categories above the homepage ("Categories:  
emulators, aqua") but port info doesn't show that now; it currently  
shows "emulators/minivmac" which isn't the categories; it's the path.  
And I certainly don't need that. If I did, I could always type "port  
dir minivmac".

After the blank line, the word-wrapped description. I wouldn't indent  
subsequent lines here; it looks weird. I think the blank lines above  
and below are sufficient. Note that I would like the long_description  
to be able to include newlines; I don't know how to do that  
currently, or even if it's possible.

Then the variants section, which I expand a little from my last mail.  
The label "Variants:" followed by a list of all variants, each  
indented on their own line, with their descriptions, if available. If  
the description is too long, word wrap to the next line and indent.  
If the port has no variants, this section is not shown. Automatic  
variants like "macosx" and "darwin_8" are not shown, because variants  
(at least the list of variants I want shown to the user) are things  
the user consciously selects. Perhaps we should distinguish between  
variants created by the base system (currently only "universal") and  
those created by the portfile (all the others). Not sure how to  
indicate this distinction yet. Maybe list the global variants  
separately, after the portfile-specific ones, with the label "Global  
Variants:" or "Globally-Available Variants:" That's a bit wordy. I've  
also added an asterisk in front of the variants which will be  
automatically selected, which we should be indicating somehow. In  
this example, +macplus will be selected because the portfile says so  
with default_variants, while +universal might be selected because a  
user might have put it in their variants.conf.

I forgot about dependencies last time because minivmac doesn't have  
any. I don't see a pressing need to change the way the dependencies  
are displayed so I'm leaving them alone.

Then the maintainers, comma-separated, just like the dependencies,  
because that's prettier than spaces. Word wrap to new line and indent  
if necessary. We should special-case the special email addresses:

- If openmaintainer at macports.org is in the list of maintainers, then  
the remaining maintainers should be printed, and this should be  
followed with a blank line and some text like "Note: This port is  
under open maintainership. You are free to make changes to this port  
as you see fit. For major changes, please attempt to contact the  
maintainer(s) first."

- If nomaintainer at macports.org is the only maintainer (or if  
openmaintainer at macports.org is the only maintainer, or if  
nomaintainer at macports.org and openmaintainer at macports.org are the  
only maintainers -- neither of which should happen but let's cover  
our bases), then the maintainers section should not be printed, and  
instead we should see some other text, like "Note: This port has no  
maintainer. You are free to make changes to this port as you see fit.  
If you are interested in this software, please consider becoming the  
port's maintainer."

If you have other ideas, please modify the mockup as you wish and  
describe.


On Apr 29, 2007, at 01:46, Mark D wrote:

> I agree that we need descriptions.  I'd vote for  
> variant_description.  I'd
> also say that out 'port info' and other commands that display this
> information need formatting changes.  They don't put out  
> information in a
> way that the eye scans well.  It is output only a computer could love.
> For example, each item should have a title preceding it, and each item
> that has multiple lines should indent the text that follows.  Or  
> some such
> scheme that the eye can scan easily.  Right now the display makes my
> eyeballs work too hard and I sometimes just open it in an editor to  
> see
> that info.
>
> Mark
>
>
> Ryan Schmidt on Saturday, April 28, 2007 at 11:25 PM -0800 wrote:
>
>> How hard would it be to let variants have descriptions? I think the
>> time has come for that feature to be implemented. Sometimes the
>> single word or abbreviation comprising the variant name just really
>> isn't enough information for the user to fully understand what the
>> variant does. I have been trying to add descriptions to my ports'
>> variants, in the comments in the portfile, but I would like to be
>> able to display these to the user.
>>
>> I see two necessary steps:
>>
>>
>> 1) Allow some (optional!) syntax within the variant to specify a
>> description, like
>>
>> variant macplus {
>> 	description Emulate a Macintosh Plus with 4 MB RAM and 6 drives
>> 	...
>> }
>>
>> or
>>
>> variant macplus {
>> 	variant_description Emulate a Macintosh Plus with 4 MB RAM and 6  
>> drives
>> 	...
>> }
>>
>>
>> 2) Modify the display of "port info" to show the variant description,
>> like
>>
>>
>> $ port info minivmac
>> minivmac 2.8.2, Revision 1, emulators/minivmac
>> http://minivmac.sourceforge.net/
>>
>> Mini vMac is a Macintosh emulator. It emulates the earliest Macs,
>> from the original Mac 128K (built 1984-85) to the Mac SE (1987-1990).
>> The default is to emulate a Mac Plus (1986-1990); this is also the
>> best-tested and therefore recommended emulation. To use Mini vMac,
>> you need a ROM file from the type of machine you're emulating. Mac
>> ROMs are copyrighted by Apple, so you must extract the ROM from a
>> real physical Mac that you own. Use the CopyROM program for this,
>> which you can download from the Mini vMac web site (More > Extras).
>>
>> Variants:
>> 	universal: Build a universal binary
>> 	mac128k: Emulate a Macintosh with 128K RAM and 2 drives
>> 	mac512k: Emulate a Macintosh 512K with 512K RAM and 2 drives
>> 	mac512ke: Emulate a Macintosh 512Ke with 512K RAM and 6 drives
>> 	macplus: Emulate a Macintosh Plus with 4 MB RAM and 6 drives
>> 	macse: Emulate a Macintosh SE with 4 MB RAM and 6 drives
>>
>> Maintainers: ryandesign at macports.org
>>
>>
>> Variants that have no description (i.e. all variants currently) would
>> show up just like that, but with just the variant name and no colon
>> afterward:
>>
>>
>> Variants:
>> 	universal
>> 	mac128k
>> 	etc.
>>
>>
>> Note that I think the automatic platform variants like macosx and
>> darwin_8 should not appear at all in port info.
>>
>>
>> Comments?