> I'd like to add a paragraph of text to my usage message, describing  
> the non-option arguments accepted by my script.

example of working class below.

vlad

 # require 'rubygems'
  require 'optparse'
  require 'pp'
  require 'ostruct'
  
  class Options
    def self.parse(args)
      options = OpenStruct.new
    
      # load defaults from lugat.yaml here

      option_parser = OptionParser.new do |opts|
        opts.banner = "usage: \n\t lugat.rb [options]"
        opts.separator("")
        opts.separator("common options:")
      
        opts.on("-v", "--verbose", "be verbose") do |verbose|
          options.verbose = verbose
        end

        opts.separator("specific options:")
      
        explanation = <<-EOE
    if you want to specify the numerical values for the user or group id,
    use <name1>:<numerical-id1>,<name2>:<numerical-id2>,... form,

    for example:
                  lugat.rb -A -u bob:2001,jan:2002
    will add the two users with the respective numerical uids,

                  lugat.rb -A -g users:100,lpadmin:104
    will add the two groups with the respective numerical gids.

    adding users also creates the goups for them (with gid=uid) starting
    with first max unused uid.

    one can delete user from all groups by suppling * to the -g option
    (the * needs to be usually escaped so shell does not expand it)
     EOE

        opts.on("-h", "--help", "print this help") do
          puts opts
          print "\n", explanation
          exit 1
        end

        opts.on("-s", "--server LDAP_SERVER", "connect to LDAP_SERVER") do |ldap_server|
          options.ldap_server = ldap_server
        end

        opts.on("-l", "--login LDAP_LOGIN", "login to LDAP as LDAP_LOGIN") do |ldap_login|
          options.ldap_login = ldap_login
        end

        opts.on("-p", "--password LDAP_PASSWORD", "use LDAP_PASSWORD for LDAP login", "(prompted for, if not supplied)") do |ldap_password|
          options.ldap_password = ldap_password
        end

        opts.on("-u", "--user user1,user2,...", Array, "list of users to operate on") do |ldap_person|
          options.ldap_person = ldap_person
        end

        opts.on("-g", "--group group1,group2,...", Array, "list of groups to operate on") do |ldap_group|
          options.ldap_group = ldap_group
        end

        opts.separator("actions:")

        opts.on("-L", "--list", "list entries on the LDAP server") do
          options.ldap_action = :list
        end

        opts.on("-A", "--add", "add entries to the LDAP server") do
          options.ldap_action = :add
        end

        opts.on("-D", "--delete", "delete entries from the LDAP server") do
          options.ldap_action = :delete
        end

        opts.on("-C", "--check", "check entries on the LDAP server") do
          options.ldap_action = :check
        end

        opts.parse!(args)
        return options
      end # OptionParser

    end # self.parse

  end # class Options

  if ARGV.length == 0
    Options.parse(["-h"])
    exit 1
  end

  options = Options.parse(ARGV)
  pp options