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@macports.org, comaintainer@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@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@macports.org is the only maintainer (or if openmaintainer@macports.org is the only maintainer, or if nomaintainer@macports.org and openmaintainer@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@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?

On Apr 30, 2007, at 10:04, Elias Pipping wrote:

On Apr 29, 2007, at 9:55 AM, Ryan Schmidt wrote:

...

It's annoying that "port search" shows description, but "port info" only shows long_description.

Isn't that precisely what description and long_description were made for?

Is it? I don't know. It seemed to me that "port info" should show more info -- should show everything you can see with "port search" and then some. Nothing that you can see with "port search" (i.e. the (short) description) should be omitted. Though I have seen some portfiles that set the description and long_description to the same thing, so those would look silly in "port info" if it were changed to show both strings. Though these ports currently already look silly in "port info" because it prints curly braces around the long description. For example: $ port info p5-archive-tar p5-archive-tar 1.30, perl/p5-archive-tar (Variants: universal) http://search.cpan.org/dist/Archive-Tar/ {Creation and in-memory manipulation of tar files} Library Dependencies: perl5.8, p5-io-zlib, p5-text-diff Platforms: darwin Maintainers: narf_tm@macports.org