From: Charles Comstock <cc1@...>
Date: 2004-05-01T11:23:59+09:00
Subject: Re: [ANN] RubyGems 0.3.0 -- and commentary about use of --help on projects

Also, noticed with gem -l, it might be nice to only display the up to 
date versions in this list.  There is really no need to display all 6 or 
so editions of Redcloth, maybe have a complete listing as an additional 
switch?  For that matter, while it is definitely cool to see the 
description, it might be nice to have that also show up optionally, or 
something.

Finally and this applies to a few people, it's really nice if the 
majority of a file --help call displays the majority of the help options 
on one page, obviously in some cases that isn't possible, but it's 
better to stuff some of the info there into a man page or something, or 
some form of --help-blah which is mentioned in the --help listing.  I 
mean obviously this can't always happen, but it's nice if for quick 
typing if you don't HAVE to pipe it to less.  For instance I noticed on 
both rodc --help and gem --help there are blank lines between each 
command option.  I realize it makes it a little easier to read, but I 
guess I'm just used to --help as a quickref which means it's dense, but 
readable, not as the majority of the help system.  Ruby and Rake have 
the right idea on the length.  I generally run a 40 row terminal and I 
should be able to view the majority of --help on one screen, unless it's 
something with as many options as say tar.

Anyway, I think these are all excellent tools, I guess it's just a style 
issue that I wanted to point out.  Sorry about being so critical, I mean 
no offence.  I know man pages aren't that fun to write and I know there 
isn't an equivalent on windows, but maybe application help could be 
listed in ri or something?  It would be nice to try to keep as many 
--help lists for quick reference, not extended documentation.

Charles Comstock