[Rubygems-developers] Modified usage information, and several suggestions

[Gavin Sinclair]

Folks,

I noticed the --help information was a bit cluttered and modified the
source to improve it.  The patch is at EOF; the new output is below.

<output>

'gem' is the user interface to RubyGems, the Ruby package manager.

    Usage: gem <action> [modifier ...]"

Actions:

  Install:
    -i, --install GEMFILE            Install a gem from local gem file
    -u, --uninstall GEMNAME          Uninstall a previously installed gem
    -r, --remote-install GEMNAME     Auto-download and install a gem and its dependencies

  Build:
    -b, --build GEMSPEC              Build a gem file from spec

  Query:
    -l, --list                       List installed gems
    -s, --search SEARCHPATTERN       Search for gems in the remote repository
        --info GEMNAME               Display details about an installed gem
        --remote-list                List all gems in the remote repository

  Miscellaneous:
        --alien                      Report 'unmanaged' or rogue files in the gem repository
        --verify GEMFILE             Verify gem file against its internal checksum

Modifiers:
        --dir DIRNAME                Installation directory for the gem
        --force                      Force gem to intall, bypassing dependency checks
        --gen-rdoc                   Generate RDoc documentation for the gem
        --http-proxy HTTPPROXYHOST   (unimplemented) HTTP Proxy to use for remote operations
        --version GEMVERSION         Version of gem to perform operation on

Miscellaneous:
        --help                       show this message
        
</output>


Notes:
 1. I've removed the "=" characters, which is a matter of taste.  My
    justification is that they're unnecessary and they make it harder
    to read.  Consider this before committing.

 2. I would like to make the following changes, but only suggest them
    at this stage: --search should search *locally*, and
    --remote-search should be provided for what --search does now.
    This would be consistent with --list and --remote-list.

 3. I made '-r' an alias for '--remote-install'.  '-r' may be a poor
    choice, but something is necessary.

 4. Suggestion: interactive mode, making it easier to browse the
    remote repository and install, etc.  That's a bit far out for now
    and not a core competency.

 5. Suggestion: 'gem --gen-rdoc GEMNAME' to generate the RDoc for an
    already-installed gem.  '--gen-rdoc' exists at the moment, but can
    only be used (AFAIK) when installing a gem.

 6. Suggestion: 'gem --browse', which runs a Webrick app and opens a
    web browser allowing you to browse your installed gems (and query
    remote ones, perhaps), including description and generated
    documentation.

 7. Pursuant to (2) above, think about this: we have installing,
    searching, listing, and displaying info. And orthogonally, we have
    local and remote operations. What about this sort of interface
    instead of what we have now?

      gem -i jabber4r
        * looks for local gemfile
        * failing that, looks for remote one if possible

      gem -s doom
        * searches local packages for 'doom' and reports
        * also performs remote search if possible and reports
          separately
        * note this implies -s as shortcut for --search

      gem --list F
        * lists local gems beginning with 'F'
          * argument 'F' is optional and case insensitive
        * lists remote gems if possible

      gem --info jabber4r
        * looks locally for package information
        * attempts remote lookup so
          * we get the information even if it's not installed locally
          * we can see if there's a more recent version

     All the above examples describe *default* behaviour.  The
     modifiers --local and --remote force them to behave one way or the
     other.

     I'm happy to do the work on this (yeah, you've heard that before)
     but obviously the idea needs buy-in.  I'm really busy ATM but this
     stuff ain't hard.

     Q: is there an easy and quick way to determine whether a computer
     is connected to the internet?

  8. Now that everyone's using Ruby 1.8 (that's assumed for RubyGems
     isn't it?), and therefore RDoc is installed, let's make gem
     installation include RDoc generation by default.

  9. When performing a search, display the N closest matches (where
     0 < N <= 5).  This is really easy.  I've mentioned this on
     ruby-talk but may as well include it here.

 10. Suggestion: 'gem --updates' to inform you of available updates to
     packages you already have installed.

 11. Worth having a man page?


Below is the patch for achieving the --help output specified above.

Cheers,
Gavin



Index: bin/gem
===================================================================
RCS file: /var/cvs/rubygems/rubygems/bin/gem,v
retrieving revision 1.32
diff -u -u -r1.32 gem
--- bin/gem     17 Mar 2004 02:55:37 -0000      1.32
+++ bin/gem     17 Mar 2004 13:34:02 -0000
@@ -4,22 +4,42 @@
 
 options = {}
 ARGV.options do |opts|
-  opts.on_tail("--help", "show this message") {puts opts; exit}
-  opts.on('-bGEMSPEC','--build=GEMSPEC', "Build a gem file from spec") { |options[:gemspec]| }
-  opts.on('-iGEMFILE', '--install=GEMFILE', "Install a gem from local gem file")    {|options[:install]|}
-  opts.on('-uGEMNAME', '--uninstall=GEMNAME', "Uninstall a previously installed gem") {|options[:uninstall]|}
-  opts.on('--info=GEMNAME', "Display details about an installed gem") {|options[:info]|}
-  opts.on('--dir=DIRNAME', "Installation directory for the gem") {|options[:directory]|}
-  opts.on('--gen-rdoc', "Generate RDoc documentation for the gem") {|options[:gen_rdoc]|}
-  opts.on('--list', "List installed gems") {|options[:list]|}
-  opts.on('--search=SEARCHPATTERN', "Search for gems in the remote repository") {|options[:search]|}
+  opts.banner = <<BANNER
+
+'gem' is the user interface to RubyGems, the Ruby package manager.
+  
+    Usage: gem <action> [modifier ...]"
+BANNER
+  opts.separator("")
+  opts.separator("Actions:")
+  opts.separator("")
+  opts.separator("  Install:")
+  opts.on('-i', '--install GEMFILE', "Install a gem from local gem file")    {|options[:install]|}
+  opts.on('-u', '--uninstall GEMNAME', "Uninstall a previously installed gem") {|options[:uninstall]|}
+  opts.on('-r', '--remote-install GEMNAME', "Auto-download and install a gem and its dependencies") {|options[:remote_install]|}
+  opts.separator("")
+  opts.separator("  Build:")
+  opts.on('-b', '--build GEMSPEC', "Build a gem file from spec") { |options[:gemspec]| }
+  opts.separator("")
+  opts.separator("  Query:")
+  opts.on('-l', '--list', "List installed gems") {|options[:list]|}
+  opts.on('-s', '--search SEARCHPATTERN', "Search for gems in the remote repository") {|options[:search]|}
+  opts.on('--info GEMNAME', "Display details about an installed gem") {|options[:info]|}
   opts.on('--remote-list', "List all gems in the remote repository") {|options[:remote_list]|}
-  opts.on('--force', "Force gem to intall, bypassing dependency checks") {|options[:force]|}
-  opts.on('--remote-install=GEMNAME', "Auto-download and install a gem and its dependencies") {|options[:remote_install]|}
-  opts.on('--http-proxy=HTTPPROXYHOST', "(unimplemented) HTTP Proxy to use for remote operations") {|options[:http_proxy]|}
-  opts.on('--version=GEMVERSION', "Version of gem to perform operation on") {|options[:gem_version]|}
-  opts.on('--verify=GEMFILE', "Verify gem file against its internal checksum") {|options[:verify_gem]|}
+  opts.separator("")
+  opts.separator("  Miscellaneous:")
   opts.on('--alien', "Report 'unmanaged' or rogue files in the gem repository") {options[:alien] = true}
+  opts.on('--verify GEMFILE', "Verify gem file against its internal checksum") {|options[:verify_gem]|}
+  opts.separator("")
+  opts.separator("Modifiers:")
+  opts.on('--dir DIRNAME', "Installation directory for the gem") {|options[:directory]|}
+  opts.on('--force', "Force gem to intall, bypassing dependency checks") {|options[:force]|}
+  opts.on('--gen-rdoc', "Generate RDoc documentation for the gem") {|options[:gen_rdoc]|}
+  opts.on('--http-proxy HTTPPROXYHOST', "(unimplemented) HTTP Proxy to use for remote operations") {|options[:http_proxy]|}
+  opts.on('--version GEMVERSION', "Version of gem to perform operation on") {|options[:gem_version]|}
+  opts.separator("")
+  opts.separator("Miscellaneous:")
+  opts.on("--help", "show this message") {puts opts; exit}
   opts.parse!
 end