Rdoc for help

doc/optparse/argument_converters.rdoc

@@ -345,8 +345,14 @@ Executions:
 === Custom Argument Converters
 
 You can create custom argument converters.
-To create a custom converter, call OptionParser#accept with a class argument,
-along with a block that converts the argument and returns the converted value.
+To create a custom converter, call OptionParser#accept with:
+
+- An identifier, which may be any object.
+- An optional match pattern, which defaults to <tt>/.*/m</tt>.
+- A block that accepts the argument and returns the converted value.
+
+This custom converter accepts any argument and converts it,
+if possible, to a \Complex object.
 
   :include: ruby/custom_converter.rb
 
@@ -360,3 +366,15 @@ Executions:
   [(1+2i), Complex]
   $ ruby custom_converter.rb --complex 0.3-0.5i
   [(0.3-0.5i), Complex]
+
+This custom converter accepts any 1-word argument
+and capitalizes it, if possible.
+
+  :include: ruby/match_converter.rb
+
+Executions:
+
+  $ ruby match_converter.rb --capitalize foo
+  ["Foo", String]
+  $ ruby match_converter.rb --capitalize "foo bar"
+  match_converter.rb:9:in `<main>': invalid argument: --capitalize foo bar (OptionParser::InvalidArgument)

doc/optparse/ruby/basic.rb

@@ -0,0 +1,16 @@
+# Require the OptionParser code.
+require 'optparse'
+# Create an OptionParser object.
+parser = OptionParser.new
+# Define one or more options.
+parser.on('-x', 'Whether to X') do |value|
+  p ['x', value]
+end
+parser.on('-y', 'Whether to Y') do |value|
+  p ['y', value]
+end
+parser.on('-z', 'Whether to Z') do |value|
+  p ['z', value]
+end
+# Parse the command line.
+parser.parse!

doc/optparse/ruby/help.rb

@@ -0,0 +1,21 @@
+require 'optparse'
+parser = OptionParser.new
+parser.on(
+  '-x', '--xxx',
+  'Adipiscing elit. Aenean commodo ligula eget.',
+  'Aenean massa. Cum sociis natoque penatibus',
+  )
+parser.on(
+  '-y', '--yyy YYY',
+  'Lorem ipsum dolor sit amet, consectetuer.'
+)
+parser.on(
+  '-z', '--zzz [ZZZ]',
+  'Et magnis dis parturient montes, nascetur',
+  'ridiculus mus. Donec quam felis, ultricies',
+  'nec, pellentesque eu, pretium quis, sem.',
+  )
+parser.parse!
+
+
+

doc/optparse/ruby/help_banner.rb

@@ -0,0 +1,7 @@
+require 'optparse'
+parser = OptionParser.new
+parser.banner = "Usage: ruby help_banner.rb"
+parser.parse!
+
+
+

doc/optparse/ruby/help_format.rb

@@ -0,0 +1,25 @@
+require 'optparse'
+parser = OptionParser.new(
+  'ruby help_format.rb [options]', # Banner
+  20,                               # Width of options field
+  ' ' * 2                               # Indentation
+)
+parser.on(
+  '-x', '--xxx',
+  'Adipiscing elit. Aenean commodo ligula eget.',
+  'Aenean massa. Cum sociis natoque penatibus',
+  )
+parser.on(
+  '-y', '--yyy YYY',
+  'Lorem ipsum dolor sit amet, consectetuer.'
+)
+parser.on(
+  '-z', '--zzz [ZZZ]',
+  'Et magnis dis parturient montes, nascetur',
+  'ridiculus mus. Donec quam felis, ultricies',
+  'nec, pellentesque eu, pretium quis, sem.',
+  )
+parser.parse!
+
+
+

doc/optparse/ruby/help_program_name.rb

@@ -0,0 +1,7 @@
+require 'optparse'
+parser = OptionParser.new
+parser.program_name = 'help_program_name.rb'
+parser.parse!
+
+
+

doc/optparse/ruby/match_converter.rb

@@ -0,0 +1,9 @@
+require 'optparse/date'
+parser = OptionParser.new
+parser.accept(:capitalize, /\w*/) do |value|
+  value.capitalize
+end
+parser.on('--capitalize XXX', :capitalize) do |value|
+  p [value, value.class]
+end
+parser.parse!

doc/optparse/tutorial.rdoc

@@ -1,6 +1,6 @@
 == Tutorial
 
-=== Why OptionParser?
+=== Why \OptionParser?
 
 When a Ruby program executes, it captures its command-line arguments
 and options into variable ARGV.
@@ -34,6 +34,7 @@ The class also has:
 
 === Contents
 
+- {To Begin With}[#label-To+Begin+With]
 - {Defining Options}[#label-Defining+Options]
 - {Option Names}[#label-Option+Names]
   - {Short Option Names}[#label-Short+Option+Names]
@@ -49,6 +50,43 @@ The class also has:
   - {Checking for Missing Options}[#label-Checking+for+Missing+Options]
   - {Default Values for Options}[#label-Default+Values+for+Options]
 - {Argument Converters}[#label-Argument+Converters]
+- {Help}[#label-Help]
+
+=== To Begin With
+
+To use \OptionParser:
+
+1. Require the \OptionParser code.
+2. Create an \OptionParser object.
+3. Define one or more options.
+4. Parse the command line.
+
+File +basic.rb+ defines three options, <tt>-x</tt>,
+<tt>-y</tt>, and <tt>-z</tt>, each with a descriptive string,
+and each with a block.
+
+  :include: ruby/basic.rb
+
+From these defined options, the parser automatically builds help text:
+
+  $ ruby basic.rb --help
+  Usage: basic [options]
+      -x                               Whether to X
+      -y                               Whether to Y
+      -z                               Whether to Z
+
+When an option is found during parsing,
+the block defined for the option is called with the argument value.
+
+Executions:
+
+  $ ruby basic.rb -x -z
+  ["x", true]
+  ["z", true]
+  $ ruby basic.rb -z -y -x
+  ["z", true]
+  ["y", true]
+  ["x", true]
 
 === Defining Options
 
@@ -361,7 +399,6 @@ Executions:
   $ ruby default_values.rb --yyy FOO
   {:yyy=>"FOO", :zzz=>"BBB"}
 
-
 === Argument Converters
 
 An option can specify that its argument is to be converted
@@ -386,3 +423,71 @@ Executions:
 You can also define custom converters.
 See {Argument Converters}[./argument_converters_rdoc.html]
 for both built-in and custom converters.
+
+=== Help
+
+\OptionParser makes automatically generated help text available.
+
+The help text consists of:
+
+- A banner, showing the usage.
+- Option short and long names.
+- Option dummy argument names.
+- Option descriptions.
+
+Example code:
+
+  :include: ruby/help.rb
+
+The option names and dummy argument names are defined as described above.
+
+The option description consists of the strings that are not themselves option names;
+An option can have more than one description string.
+Execution:
+
+  Usage: help [options]
+      -x, --xxx                        Adipiscing elit. Aenean commodo ligula eget.
+                                       Aenean massa. Cum sociis natoque penatibus
+      -y, --yyy YYY                    Lorem ipsum dolor sit amet, consectetuer.
+      -z, --zzz [ZZZ]                  Et magnis dis parturient montes, nascetur
+                                       ridiculus mus. Donec quam felis, ultricies
+                                       nec, pellentesque eu, pretium quis, sem.
+
+The program name is included in the default banner:
+<tt>Usage: #{program_name} [options]</tt>;
+you can change the program name.
+
+  :include: ruby/help_program_name.rb
+
+Execution:
+
+  $ ruby help_program_name.rb --help
+  Usage: help_program_name.rb [options]
+
+You can also change the entire banner.
+
+  :include: ruby/help_banner.rb
+
+Execution:
+
+  $ ruby help_banner.rb --help
+  Usage: ruby help_banner.rb
+
+By default, the option names are indented 4 spaces
+and the width of the option-names field is 32 spaces.
+
+You can change these values, along with the banner,
+by passing parameters to OptionParser.new.
+
+  :include: ruby/help_format.rb
+
+Execution:
+
+  $ ruby help_format.rb --help
+  ruby help_format.rb [options]
+    -x, --xxx            Adipiscing elit. Aenean commodo ligula eget.
+                         Aenean massa. Cum sociis natoque penatibus
+    -y, --yyy YYY        Lorem ipsum dolor sit amet, consectetuer.
+    -z, --zzz [ZZZ]      Et magnis dis parturient montes, nascetur
+                         ridiculus mus. Donec quam felis, ultricies
+                         nec, pellentesque eu, pretium quis, sem.