[ruby/optparse] Rdoc (#15)

* Resolve shared mixed_names.rb

* Add long option with negation

* Show --help for all examples

* Table of contents for tutorial

* Move argument converters to separate rdoc

* Add references to argument_converters.rdoc

* Tune up argument converters

* Change explicit links to auto-links

https://github.com/ruby/optparse/commit/c91ed8d33d

10 files changed, 487 insertions, 365 deletions

diff --git a/doc/argument_converters.rdoc b/doc/argument_converters.rdoc
new file mode 100644
index 0000000000..fc5a0152a3
--- /dev/null
+++ b/doc/argument_converters.rdoc
@@ -0,0 +1,362 @@
+== Argument Converters
+
+An option can specify that its argument is to be converted
+from the default \String to an instance of another class.
+
+=== Contents
+
+- {Built-In Argument Converters}[#label-Built-In+Argument+Converters]
+  - {Date}[#label-Date]
+  - {DateTime}[#label-DateTime]
+  - {Time}[#label-Time]
+  - {URI}[#label-URI]
+  - {Shellwords}[#label-Shellwords]
+  - {Integer}[#label-Integer]
+  - {Float}[#label-Float]
+  - {Numeric}[#label-Numeric]
+  - {DecimalInteger}[#label-DecimalInteger]
+  - {OctalInteger}[#label-OctalInteger]
+  - {DecimalNumeric}[#label-DecimalNumeric]
+  - {TrueClass}[#label-TrueClass]
+  - {FalseClass}[#label-FalseClass]
+  - {Object}[#label-Object]
+  - {String}[#label-String]
+  - {Array}[#label-Array]
+  - {Regexp}[#label-Regexp]
+- {Custom Argument Converters}[#label-Custom+Argument+Converters]
+
+=== Built-In Argument Converters
+
+\OptionParser has a number of built-in argument converters,
+which are demonstrated below.
+
+==== \Date
+
+File +date.rb+
+defines an option whose argument is to be converted to a \Date object.
+The argument is converted by method Date#parse.
+
+  :include: ruby/date.rb
+
+Executions:
+
+  $ ruby date.rb --date 2001-02-03
+  [#<Date: 2001-02-03 ((2451944j,0s,0n),+0s,2299161j)>, Date]
+  $ ruby date.rb --date 20010203
+  [#<Date: 2001-02-03 ((2451944j,0s,0n),+0s,2299161j)>, Date]
+  $ ruby date.rb --date "3rd Feb 2001"
+  [#<Date: 2001-02-03 ((2451944j,0s,0n),+0s,2299161j)>, Date]
+
+==== \DateTime
+
+File +datetime.rb+
+defines an option whose argument is to be converted to a \DateTime object.
+The argument is converted by method DateTime#parse.
+
+  :include: ruby/datetime.rb
+
+Executions:
+
+  $ ruby datetime.rb --datetime 2001-02-03T04:05:06+07:00
+  [#<DateTime: 2001-02-03T04:05:06+07:00 ((2451943j,75906s,0n),+25200s,2299161j)>, DateTime]
+  $ ruby datetime.rb --datetime 20010203T040506+0700
+  [#<DateTime: 2001-02-03T04:05:06+07:00 ((2451943j,75906s,0n),+25200s,2299161j)>, DateTime]
+  $ ruby datetime.rb --datetime "3rd Feb 2001 04:05:06 PM"
+  [#<DateTime: 2001-02-03T16:05:06+00:00 ((2451944j,57906s,0n),+0s,2299161j)>, DateTime]
+
+==== \Time
+
+File +time.rb+
+defines an option whose argument is to be converted to a \Time object.
+The argument is converted by method Time#httpdate or Time#parse.
+
+  :include: ruby/time.rb
+
+Executions:
+
+  $ ruby time.rb --time "Thu, 06 Oct 2011 02:26:12 GMT"
+  [2011-10-06 02:26:12 UTC, Time]
+  $ ruby time.rb --time 2010-10-31
+  [2010-10-31 00:00:00 -0500, Time]
+
+==== \URI
+
+File +uri.rb+
+defines an option whose argument is to be converted to a \URI object.
+The argument is converted by method URI#parse.
+
+  :include: ruby/uri.rb
+
+Executions:
+
+  $ ruby uri.rb --uri https://github.com
+  [#<URI::HTTPS https://github.com>, URI::HTTPS]
+  $ ruby uri.rb --uri http://github.com
+  [#<URI::HTTP http://github.com>, URI::HTTP]
+  $ ruby uri.rb --uri file://~/var
+  [#<URI::File file://~/var>, URI::File]
+
+==== \Shellwords
+
+File +shellwords.rb+
+defines an option whose argument is to be converted to an \Array object by method
+Shellwords#shellwords.
+
+  :include: ruby/shellwords.rb
+
+Executions:
+
+  $ ruby shellwords.rb --shellwords "ruby my_prog.rb | less"
+  [["ruby", "my_prog.rb", "|", "less"], Array]
+  $ ruby shellwords.rb --shellwords "here are 'two words'"
+  [["here", "are", "two words"], Array]
+
+==== \Integer
+
+File +integer.rb+
+defines an option whose argument is to be converted to an \Integer object.
+The argument is converted by method Kernel#Integer.
+
+  :include: ruby/integer.rb
+
+Executions:
+
+  $ ruby integer.rb --integer 100
+  [100, Integer]
+  $ ruby integer.rb --integer -100
+  [-100, Integer]
+  $ ruby integer.rb --integer 0100
+  [64, Integer]
+  $ ruby integer.rb --integer 0x100
+  [256, Integer]
+  $ ruby integer.rb --integer 0b100
+  [4, Integer]
+
+==== \Float
+
+File +float.rb+
+defines an option whose argument is to be converted to a \Float object.
+The argument is converted by method Kernel#Float.
+
+  :include: ruby/float.rb
+
+Executions:
+
+  $ ruby float.rb --float 1
+  [1.0, Float]
+  $ ruby float.rb --float 3.14159
+  [3.14159, Float]
+  $ ruby float.rb --float 1.234E2
+  [123.4, Float]
+  $ ruby float.rb --float 1.234E-2
+  [0.01234, Float]
+
+==== \Numeric
+
+File +numeric.rb+
+defines an option whose argument is to be converted to an instance
+of \Rational, \Float, or \Integer.
+The argument is converted by method Kernel#Rational,
+Kernel#Float, or Kernel#Integer.
+
+  :include: ruby/numeric.rb
+
+Executions:
+
+  $ ruby numeric.rb --numeric 1/3
+  [(1/3), Rational]
+  $ ruby numeric.rb --numeric 3.333E-1
+  [0.3333, Float]
+  $ ruby numeric.rb --numeric 3
+  [3, Integer]
+
+==== \DecimalInteger
+
+File +decimal_integer.rb+
+defines an option whose argument is to be converted to an \Integer object.
+The argument is converted by method Kernel#Integer.
+
+  :include: ruby/decimal_integer.rb
+
+The argument may not be in a binary or hexadecimal format;
+a leading zero is ignored (not parsed as octal).
+
+Executions:
+
+  $ ruby decimal_integer.rb --decimal_integer 100
+  [100, Integer]
+  $ ruby decimal_integer.rb --decimal_integer -100
+  [-100, Integer]
+  $ ruby decimal_integer.rb --decimal_integer 0100
+  [100, Integer]
+  $ ruby decimal_integer.rb --decimal_integer -0100
+  [-100, Integer]
+
+==== \OctalInteger
+
+File +octal_integer.rb+
+defines an option whose argument is to be converted to an \Integer object.
+The argument is converted by method Kernel#Integer.
+
+  :include: ruby/octal_integer.rb
+
+The argument may not be in a binary or hexadecimal format;
+it is parsed as octal, regardless of whether it has a leading zero.
+
+Executions:
+
+  $ ruby octal_integer.rb --octal_integer 100
+  [64, Integer]
+  $ ruby octal_integer.rb --octal_integer -100
+  [-64, Integer]
+  $ ruby octal_integer.rb --octal_integer 0100
+  [64, Integer]
+
+==== \DecimalNumeric
+
+File +decimal_numeric.rb+
+defines an option whose argument is to be converted to an \Integer object.
+The argument is converted by method {Kernel#Integer
+
+  :include: ruby/decimal_numeric.rb
+
+The argument may not be in a binary or hexadecimal format;
+a leading zero causes the argument to be parsed as octal.
+
+Executions:
+
+  $ ruby decimal_numeric.rb --decimal_numeric 100
+  [100, Integer]
+  $ ruby decimal_numeric.rb --decimal_numeric -100
+  [-100, Integer]
+  $ ruby decimal_numeric.rb --decimal_numeric 0100
+  [64, Integer]
+
+==== \TrueClass
+
+File +true_class.rb+
+defines an option whose argument is to be converted to +true+ or +false+.
+The argument is evaluated by method Object#nil?.
+
+  :include: ruby/true_class.rb
+
+The argument may be any of those shown in the examples below.
+
+Executions:
+
+  $ ruby true_class.rb --true_class true
+  [true, TrueClass]
+  $ ruby true_class.rb --true_class yes
+  [true, TrueClass]
+  $ ruby true_class.rb --true_class +
+  [true, TrueClass]
+  $ ruby true_class.rb --true_class false
+  [false, FalseClass]
+  $ ruby true_class.rb --true_class no
+  [false, FalseClass]
+  $ ruby true_class.rb --true_class -
+  [false, FalseClass]
+  $ ruby true_class.rb --true_class nil
+  [false, FalseClass]
+
+==== \FalseClass
+
+File +false_class.rb+
+defines an option whose argument is to be converted to +true+ or +false+.
+The argument is evaluated by method Object#nil?.
+
+  :include: ruby/false_class.rb
+
+The argument may be any of those shown in the examples below.
+
+Executions:
+
+  $ ruby false_class.rb --false_class false
+  [false, FalseClass]
+  $ ruby false_class.rb --false_class no
+  [false, FalseClass]
+  $ ruby false_class.rb --false_class -
+  [false, FalseClass]
+  $ ruby false_class.rb --false_class nil
+  [false, FalseClass]
+  $ ruby false_class.rb --false_class true
+  [true, TrueClass]
+  $ ruby false_class.rb --false_class yes
+  [true, TrueClass]
+  $ ruby false_class.rb --false_class +
+  [true, TrueClass]
+
+==== \Object
+
+File +object.rb+
+defines an option whose argument is not to be converted from \String.
+
+  :include: ruby/object.rb
+
+Executions:
+
+  $ ruby object.rb --object foo
+  ["foo", String]
+  $ ruby object.rb --object nil
+  ["nil", String]
+
+==== \String
+
+File +string.rb+
+defines an option whose argument is not to be converted from \String.
+
+  :include: ruby/string.rb
+
+Executions:
+
+  $ ruby string.rb --string foo
+  ["foo", String]
+  $ ruby string.rb --string nil
+  ["nil", String]
+
+==== \Array
+
+File +array.rb+
+defines an option whose argument is to be converted from \String
+to an array of strings, based on comma-separated substrings.
+
+  :include: ruby/array.rb
+
+Executions:
+
+  $ ruby array.rb --array ""
+  [[], Array]
+  $ ruby array.rb --array foo,bar,baz
+  [["foo", "bar", "baz"], Array]
+  $ ruby array.rb --array "foo, bar, baz"
+  [["foo", " bar", " baz"], Array]
+
+==== \Regexp
+
+File +regexp.rb+
+defines an option whose argument is to be converted to a \Regexp object.
+
+  :include: ruby/regexp.rb
+
+Executions:
+
+  $ ruby regexp.rb --regexp foo
+
+=== 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.
+
+  :include: ruby/custom_converter.rb
+
+Executions:
+
+  $ ruby custom_converter.rb --complex 0
+  [(0+0i), Complex]
+  $ ruby custom_converter.rb --complex 1
+  [(1+0i), Complex]
+  $ ruby custom_converter.rb --complex 1+2i
+  [(1+2i), Complex]
+  $ ruby custom_converter.rb --complex 0.3-0.5i
+  [(0.3-0.5i), Complex]
diff --git a/doc/option_params.rdoc b/doc/option_params.rdoc
index 98d9630a38..0d06b41e7d 100644
--- a/doc/option_params.rdoc
+++ b/doc/option_params.rdoc
@@ -29,6 +29,7 @@ Contents:
     - {Simple Long Names}[#label-Simple+Long+Names]
     - {Long Names with Required Arguments}[#label-Long+Names+with+Required+Arguments]
     - {Long Names with Optional Arguments}[#label-Long+Names+with+Optional+Arguments]
+    - {Long Names with Negation}[#label-Long+Names+with+Negation]
   - {Mixed Names}[#label-Mixed+Names]
 - {Argument Styles}[#label-Argument+Styles]
 - {Argument Values}[#label-Argument+Values]
@@ -37,23 +38,6 @@ Contents:
     - {Explicit Values in Hash}[#label-Explicit+Values+in+Hash]
   - {Argument Value Patterns}[#label-Argument+Value+Patterns]
 - {Argument Converters}[#label-Argument+Converters]
-  - {Date}[#label-Date]
-  - {DateTime}[#label-DateTime]
-  - {Time}[#label-Time]
-  - {URI}[#label-URI]
-  - {Shellwords}[#label-Shellwords]
-  - {Integer}[#label-Integer]
-  - {Float}[#label-Float]
-  - {Numeric}[#label-Numeric]
-  - {DecimalInteger}[#label-DecimalInteger]
-  - {OctalInteger}[#label-OctalInteger]
-  - {DecimalNumeric}[#label-DecimalNumeric]
-  - {TrueClass}[#label-TrueClass]
-  - {FalseClass}[#label-FalseClass]
-  - {Object}[#label-Object]
-  - {String}[#label-String]
-  - {Array}[#label-Array]
-  - {Regexp}[#label-Regexp]
 - {Descriptions}[#label-Descriptions]
 - {Option Handlers}[#label-Option+Handlers]
   - {Handler Blocks}[#label-Handler+Blocks]
@@ -222,6 +206,24 @@ Executions:
   $ ruby long_optional.rb --xxx FOO
   ["--xxx", "FOO"]
 
+===== Long Names with Negation
+
+A long name may be defined with both positive and negative senses.
+
+File +long_with_negation.rb+ defines an option that has both senses.
+
+  :include: ruby/long_with_negation.rb
+
+Executions:
+
+  $ ruby long_with_negation.rb --help
+  Usage: long_with_negation [options]
+          --[no-]binary                Long name with negation
+  $ ruby long_with_negation.rb --binary
+  [true, TrueClass]
+  $ ruby long_with_negation.rb --no-binary
+  [false, FalseClass]
+
 ==== Mixed Names
 
 An option may have both short and long names.
@@ -233,12 +235,10 @@ File +mixed_names.rb+ defines a mixture of short and long names.
 Executions:
 
   $ ruby mixed_names.rb --help
-  Usage: mixed_names [options]
-      -x, --xxx                        Short and long, simple
-          --yyy                        yYYY
-                                       Short and long, required argument
-          --zzz                        zZZZ
-                                       Short and long, optional argument
+Usage: mixed_names [options]
+    -x, --xxx                        Short and long, no argument
+    -y, --yyyYYY                     Short and long, required argument
+    -z, --zzz [ZZZ]                  Short and long, optional argument
   $ ruby mixed_names.rb -x
   ["--xxx", true]
   $ ruby mixed_names.rb --xxx
@@ -400,334 +400,10 @@ Executions:
 An option can specify that its argument is to be converted
 from the default \String to an instance of another class.
 
-\OptionParser has a number of built-in converters,
-which are demonstrated below.
-
-==== \Date
-
-File +date.rb+
-defines an option whose argument is to be converted to a \Date object.
-The argument is converted by method
-{Date.parse}[https://ruby-doc.org/stdlib/libdoc/date/rdoc/Date.html#method-c-parse].
-
-  :include: ruby/date.rb
-
-Executions:
-
-  $ ruby date.rb --date 2001-02-03
-  [#<Date: 2001-02-03 ((2451944j,0s,0n),+0s,2299161j)>, Date]
-  $ ruby date.rb --date 20010203
-  [#<Date: 2001-02-03 ((2451944j,0s,0n),+0s,2299161j)>, Date]
-  $ ruby date.rb --date "3rd Feb 2001"
-  [#<Date: 2001-02-03 ((2451944j,0s,0n),+0s,2299161j)>, Date]
-
-==== \DateTime
-
-File +datetime.rb+
-defines an option whose argument is to be converted to a \DateTime object.
-The argument is converted by method
-{DateTime.parse}[https://ruby-doc.org/stdlib-2.6.1/libdoc/date/rdoc/DateTime.html#method-c-parse].
-
-  :include: ruby/datetime.rb
-
-Executions:
-
-  $ ruby datetime.rb --datetime 2001-02-03T04:05:06+07:00
-  [#<DateTime: 2001-02-03T04:05:06+07:00 ((2451943j,75906s,0n),+25200s,2299161j)>, DateTime]
-  $ ruby datetime.rb --datetime 20010203T040506+0700
-  [#<DateTime: 2001-02-03T04:05:06+07:00 ((2451943j,75906s,0n),+25200s,2299161j)>, DateTime]
-  $ ruby datetime.rb --datetime "3rd Feb 2001 04:05:06 PM"
-  [#<DateTime: 2001-02-03T16:05:06+00:00 ((2451944j,57906s,0n),+0s,2299161j)>, DateTime]
-
-==== \Time
-
-File +time.rb+
-defines an option whose argument is to be converted to a \Time object.
-The argument is converted by method
-{Time.httpdate}[https://ruby-doc.org/stdlib-2.7.0/libdoc/time/rdoc/Time.html#method-c-httpdate] or
-{Time.parse}[https://ruby-doc.org/stdlib-2.7.0/libdoc/time/rdoc/Time.html#method-c-parse].
-
-  :include: ruby/time.rb
-
-Executions:
-
-  $ ruby time.rb --time "Thu, 06 Oct 2011 02:26:12 GMT"
-  [2011-10-06 02:26:12 UTC, Time]
-  $ ruby time.rb --time 2010-10-31
-  [2010-10-31 00:00:00 -0500, Time]
-
-==== \URI
-
-File +uri.rb+
-defines an option whose argument is to be converted to a \URI object.
-The argument is converted by method
-{URI.parse}[https://ruby-doc.org/stdlib-2.7.2/libdoc/uri/rdoc/URI.html#method-c-parse].
-
-  :include: ruby/uri.rb
-
-Executions:
-
-  $ ruby uri.rb --uri https://github.com
-  [#<URI::HTTPS https://github.com>, URI::HTTPS]
-  $ ruby uri.rb --uri http://github.com
-  [#<URI::HTTP http://github.com>, URI::HTTP]
-  $ ruby uri.rb --uri file://~/var
-  [#<URI::File file://~/var>, URI::File]
-
-==== \Shellwords
-
-File +shellwords.rb+
-defines an option whose argument is to be converted to an \Array object by method
-{Shellwords.shellwords}[https://ruby-doc.org/stdlib-2.7.0/libdoc/shellwords/rdoc/Shellwords.html#method-c-shellwords].
-
-  :include: ruby/shellwords.rb
-
-Executions:
-
-  $ ruby shellwords.rb --shellwords "ruby my_prog.rb | less"
-  [["ruby", "my_prog.rb", "|", "less"], Array]
-  $ ruby shellwords.rb --shellwords "here are 'two words'"
-  [["here", "are", "two words"], Array]
-
-==== \Integer
-
-File +integer.rb+
-defines an option whose argument is to be converted to an \Integer object.
-The argument is converted by method
-{Kernel.Integer}[https://ruby-doc.org/core/Kernel.html#method-i-Integer].
-
-  :include: ruby/integer.rb
-
-Executions:
-
-  $ ruby integer.rb --integer 100
-  [100, Integer]
-  $ ruby integer.rb --integer -100
-  [-100, Integer]
-  $ ruby integer.rb --integer 0100
-  [64, Integer]
-  $ ruby integer.rb --integer 0x100
-  [256, Integer]
-  $ ruby integer.rb --integer 0b100
-  [4, Integer]
-
-==== \Float
-
-File +float.rb+
-defines an option whose argument is to be converted to a \Float object.
-The argument is converted by method
-{Kernel.Float}[https://ruby-doc.org/core/Kernel.html#method-i-Float].
-
-  :include: ruby/float.rb
-
-Executions:
-
-  $ ruby float.rb --float 1
-  [1.0, Float]
-  $ ruby float.rb --float 3.14159
-  [3.14159, Float]
-  $ ruby float.rb --float 1.234E2
-  [123.4, Float]
-  $ ruby float.rb --float 1.234E-2
-  [0.01234, Float]
-
-==== \Numeric
-
-File +numeric.rb+
-defines an option whose argument is to be converted to an instance
-of \Rational, \Float, or \Integer.
-The argument is converted by method
-{Kernel.Rational}[https://ruby-doc.org/core/Kernel.html#method-i-Rational],
-{Kernel.Float}[https://ruby-doc.org/core/Kernel.html#method-i-Float], or
-{Kernel.Integer}[https://ruby-doc.org/core/Kernel.html#method-i-Integer].
-
-  :include: ruby/numeric.rb
-
-Executions:
-
-  $ ruby numeric.rb --numeric 1/3
-  [(1/3), Rational]
-  $ ruby numeric.rb --numeric 3.333E-1
-  [0.3333, Float]
-  $ ruby numeric.rb --numeric 3
-  [3, Integer]
-
-==== \DecimalInteger
-
-File +decimal_integer.rb+
-defines an option whose argument is to be converted to an \Integer object.
-The argument is converted by method
-{Kernel.Integer}[https://ruby-doc.org/core/Kernel.html#method-i-Integer].
-
-  :include: ruby/decimal_integer.rb
-
-The argument may not be in a binary or hexadecimal format;
-a leading zero is ignored (not parsed as octal).
-
-Executions:
-
-  $ ruby decimal_integer.rb --decimal_integer 100
-  [100, Integer]
-  $ ruby decimal_integer.rb --decimal_integer -100
-  [-100, Integer]
-  $ ruby decimal_integer.rb --decimal_integer 0100
-  [100, Integer]
-  $ ruby decimal_integer.rb --decimal_integer -0100
-  [-100, Integer]
-
-==== \OctalInteger
-
-File +octal_integer.rb+
-defines an option whose argument is to be converted to an \Integer object.
-The argument is converted by method
-{Kernel.Integer}[https://ruby-doc.org/core/Kernel.html#method-i-Integer].
-
-  :include: ruby/octal_integer.rb
-
-The argument may not be in a binary or hexadecimal format;
-it is parsed as octal, regardless of whether it has a leading zero.
-
-Executions:
-
-  $ ruby octal_integer.rb --octal_integer 100
-  [64, Integer]
-  $ ruby octal_integer.rb --octal_integer -100
-  [-64, Integer]
-  $ ruby octal_integer.rb --octal_integer 0100
-  [64, Integer]
-
-==== \DecimalNumeric
-
-File +decimal_numeric.rb+
-defines an option whose argument is to be converted to an \Integer object.
-The argument is converted by method
-{Kernel.Integer}[https://ruby-doc.org/core/Kernel.html#method-i-Integer].
-
-  :include: ruby/decimal_numeric.rb
-
-The argument may not be in a binary or hexadecimal format;
-a leading zero causes the argument to be parsed as octal.
-
-Executions:
-
-  $ ruby decimal_numeric.rb --decimal_numeric 100
-  [100, Integer]
-  $ ruby decimal_numeric.rb --decimal_numeric -100
-  [-100, Integer]
-  $ ruby decimal_numeric.rb --decimal_numeric 0100
-  [64, Integer]
-
-==== \TrueClass
-
-File +true_class.rb+
-defines an option whose argument is to be converted to +true+ or +false+.
-The argument is evaluated by method
-{Object#nil?}[https://ruby-doc.org/core-3.0.0/Object.html#method-i-nil-3F].
-
-  :include: ruby/true_class.rb
-
-The argument may be any of those shown in the examples below.
-
-Executions:
-
-  $ ruby true_class.rb --true_class true
-  [true, TrueClass]
-  $ ruby true_class.rb --true_class yes
-  [true, TrueClass]
-  $ ruby true_class.rb --true_class +
-  [true, TrueClass]
-  $ ruby true_class.rb --true_class false
-  [false, FalseClass]
-  $ ruby true_class.rb --true_class no
-  [false, FalseClass]
-  $ ruby true_class.rb --true_class -
-  [false, FalseClass]
-  $ ruby true_class.rb --true_class nil
-  [false, FalseClass]
-
-==== \FalseClass
-
-File +false_class.rb+
-defines an option whose argument is to be converted to +true+ or +false+.
-The argument is evaluated by method
-{Object#nil?}[https://ruby-doc.org/core-3.0.0/Object.html#method-i-nil-3F].
-
-  :include: ruby/false_class.rb
-
-The argument may be any of those shown in the examples below.
-
-Executions:
-
-  $ ruby false_class.rb --false_class false
-  [false, FalseClass]
-  $ ruby false_class.rb --false_class no
-  [false, FalseClass]
-  $ ruby false_class.rb --false_class -
-  [false, FalseClass]
-  $ ruby false_class.rb --false_class nil
-  [false, FalseClass]
-  $ ruby false_class.rb --false_class true
-  [true, TrueClass]
-  $ ruby false_class.rb --false_class yes
-  [true, TrueClass]
-  $ ruby false_class.rb --false_class +
-  [true, TrueClass]
-
-==== \Object
-
-File +object.rb+
-defines an option whose argument is not to be converted from \String.
-
-  :include: ruby/object.rb
-
-Executions:
-
-  $ ruby object.rb --object foo
-  ["foo", String]
-  $ ruby object.rb --object nil
-  ["nil", String]
-
-==== \String
-
-File +string.rb+
-defines an option whose argument is not to be converted from \String.
-
-  :include: ruby/string.rb
-
-Executions:
-
-  $ ruby string.rb --string foo
-  ["foo", String]
-  $ ruby string.rb --string nil
-  ["nil", String]
-
-==== \Array
-
-File +array.rb+
-defines an option whose argument is to be converted from \String
-to an array of strings, based on comma-separated substrings.
-
-  :include: ruby/array.rb
-
-Executions:
-
-  $ ruby array.rb --array ""
-  [[], Array]
-  $ ruby array.rb --array foo,bar,baz
-  [["foo", "bar", "baz"], Array]
-  $ ruby array.rb --array "foo, bar, baz"
-  [["foo", " bar", " baz"], Array]
-
-==== \Regexp
-
-File +regexp.rb+
-defines an option whose argument is to be converted to a \Regexp object.
-
-  :include: ruby/regexp.rb
-
-Executions:
+There are a number of built-in converters.
+You can also define custom converters.
 
-  $ ruby regexp.rb --regexp foo
+See {Argument Converters}[./argument_converters_rdoc.html].
 
 === Descriptions
 
diff --git a/doc/ruby/custom_converter.rb b/doc/ruby/custom_converter.rb
new file mode 100644
index 0000000000..029da08c46
--- /dev/null
+++ b/doc/ruby/custom_converter.rb
@@ -0,0 +1,9 @@
+require 'optparse/date'
+parser = OptionParser.new
+parser.accept(Complex) do |value|
+  value.to_c
+end
+parser.on('--complex COMPLEX', Complex) do |value|
+  p [value, value.class]
+end
+parser.parse!
diff --git a/doc/ruby/long_names.rb b/doc/ruby/long_names.rb
index a34b3382c2..a49dbda69f 100644
--- a/doc/ruby/long_names.rb
+++ b/doc/ruby/long_names.rb
@@ -1,9 +1,9 @@
 require 'optparse'
 parser = OptionParser.new
-parser.on('--xxx') do |value|
+parser.on('--xxx', 'Long name') do |value|
   p ['-xxx', value]
 end
-parser.on('--y1%', '--z2#') do |value|
+parser.on('--y1%', '--z2#', "Two long names") do |value|
   p ['--y1% or --z2#', value]
 end
 parser.parse!
diff --git a/doc/ruby/long_binary.rb b/doc/ruby/long_with_negation.rb
index 8eccecaf3a..3f2913c361 100644
--- a/doc/ruby/long_binary.rb
+++ b/doc/ruby/long_with_negation.rb
@@ -1,6 +1,6 @@
 require 'optparse'
 parser = OptionParser.new
-parser.on('--[no-]binary') do |value|
+parser.on('--[no-]binary', 'Long name with negation') do |value|
   p [value, value.class]
 end
 parser.parse!
diff --git a/doc/ruby/mixed_names.rb b/doc/ruby/mixed_names.rb
index e886049821..67f81e7e8d 100644
--- a/doc/ruby/mixed_names.rb
+++ b/doc/ruby/mixed_names.rb
@@ -1,9 +1,12 @@
 require 'optparse'
 parser = OptionParser.new
-parser.on('-x', '--xxx') do |value|
+parser.on('-x', '--xxx', 'Short and long, no argument') do |value|
   p ['--xxx', value]
 end
-parser.on('-y', '--y1%') do |value|
-  p ['--y1%', value]
+parser.on('-yYYY', '--yyy', 'Short and long, required argument') do |value|
+  p ['--yyy', value]
+end
+parser.on('-z [ZZZ]', '--zzz', 'Short and long, optional argument') do |value|
+  p ['--zzz', value]
 end
 parser.parse!
diff --git a/doc/ruby/optional_argument.rb b/doc/ruby/optional_argument.rb
index ebff2f466d..456368a8ba 100644
--- a/doc/ruby/optional_argument.rb
+++ b/doc/ruby/optional_argument.rb
@@ -1,9 +1,9 @@
 require 'optparse'
 parser = OptionParser.new
-parser.on('-x [XXX]', '--xxx') do |value|
+parser.on('-x [XXX]', '--xxx', 'Optional argument via short  name') do |value|
   p ['--xxx', value]
 end
-parser.on('-y', '--yyy [YYY]') do |value|
+parser.on('-y', '--yyy [YYY]', 'Optional argument via long name') do |value|
   p ['--yyy', value]
 end
 parser.parse!
diff --git a/doc/ruby/required_argument.rb b/doc/ruby/required_argument.rb
index 7a5a868265..228a492c3c 100644
--- a/doc/ruby/required_argument.rb
+++ b/doc/ruby/required_argument.rb
@@ -1,9 +1,9 @@
 require 'optparse'
 parser = OptionParser.new
-parser.on('-x XXX', '--xxx') do |value|
+parser.on('-x XXX', '--xxx', 'Required argument via short name') do |value|
   p ['--xxx', value]
 end
-parser.on('-y', '--y YYY') do |value|
+parser.on('-y', '--y YYY', 'Required argument via long name') do |value|
   p ['--yyy', value]
 end
 parser.parse!
diff --git a/doc/ruby/short_names.rb b/doc/ruby/short_names.rb
index 6581dfe19a..4a756518fa 100644
--- a/doc/ruby/short_names.rb
+++ b/doc/ruby/short_names.rb
@@ -1,9 +1,9 @@
 require 'optparse'
 parser = OptionParser.new
-parser.on('-x') do |value|
+parser.on('-x', 'Short name') do |value|
   p ['x', value]
 end
-parser.on('-1', '-%') do |value|
+parser.on('-1', '-%', 'Two short names') do |value|
   p ['-1 or -%', value]
 end
 parser.parse!
diff --git a/doc/tutorial.rdoc b/doc/tutorial.rdoc
index 5e95f20fae..42e0d1e3ac 100644
--- a/doc/tutorial.rdoc
+++ b/doc/tutorial.rdoc
@@ -32,6 +32,19 @@ The class also has:
 - Method #summarize: returns a text summary of the options.
 - Method #help: displays automatically-generated help text.
 
+=== Contents
+
+- {Defining Options}[#label-Defining+Options]
+- {Option Names}[#label-Option+Names]
+  - {Short Option Names}[#label-Short+Option+Names]
+  - {Long Option Names}[#label-Long+Option+Names]
+  - {Mixing Option Names}[#label-Mixing+Option+Names]
+- {Option Arguments}[#label-Option+Arguments]
+  - {Option with No Argument}[#label-Option+with+No+Argument]
+  - {Option with Required Argument}[#label-Option+with+Required+Argument]
+  - {Option with Optional Argument}[#label-Option+with+Optional+Argument]
+- {Argument Converters}[#label-Argument+Converters]
+
 === Defining Options
 
 A common way to define an option in \OptionParser
@@ -71,6 +84,10 @@ and an option with two short names (aliases, in effect) <tt>-y</tt> and <tt>-z</
 
 Executions:
 
+  $ ruby short_names.rb --help
+  Usage: short_names [options]
+      -x                               Short name
+      -1, -%                           Two short names
   $ ruby short_names.rb -x
   ["x", true]
   $ ruby short_names.rb -1
@@ -103,6 +120,10 @@ and an option with two long names (aliases, in effect) <tt>--y1%</tt> and <tt>--
 
 Executions:
 
+  $ ruby long_names.rb --help
+  Usage: long_names [options]
+          --xxx                        Long name
+          --y1%, --z2#                 Two long names
   $ ruby long_names.rb --xxx
   ["-xxx", true]
   $ ruby long_names.rb --y1%
@@ -110,6 +131,22 @@ Executions:
   $ ruby long_names.rb --z2#
   ["--y1% or --z2#", true]
 
+A long name may be defined with both positive and negative senses.
+
+File +long_with_negation.rb+ defines an option that has both senses.
+
+  :include: ruby/long_with_negation.rb
+
+Executions:
+
+  $ ruby long_with_negation.rb --help
+  Usage: long_with_negation [options]
+          --[no-]binary                Long name with negation
+  $ ruby long_with_negation.rb --binary
+  [true, TrueClass]
+  $ ruby long_with_negation.rb --no-binary
+  [false, FalseClass]
+
 ==== Mixing Option Names
 
 Many developers like to mix short and long option names,
@@ -122,14 +159,31 @@ defines options that each have both a short and a long name.
 
 Executions:
 
+  $ ruby mixed_names.rb --help
+  Usage: mixed_names [options]
+      -x, --xxx                        Short and long, no argument
+      -y, --yyyYYY                     Short and long, required argument
+      -z, --zzz [ZZZ]                  Short and long, optional argument
   $ ruby mixed_names.rb -x
   ["--xxx", true]
   $ ruby mixed_names.rb --xxx
   ["--xxx", true]
   $ ruby mixed_names.rb -y
-  ["--y1%", true]
-  $ ruby mixed_names.rb --y1%
-  ["--y1%", true]
+  mixed_names.rb:12:in `<main>': missing argument: -y (OptionParser::MissingArgument)
+  $ ruby mixed_names.rb -y FOO
+  ["--yyy", "FOO"]
+  $ ruby mixed_names.rb --yyy
+  mixed_names.rb:12:in `<main>': missing argument: --yyy (OptionParser::MissingArgument)
+  $ ruby mixed_names.rb --yyy BAR
+  ["--yyy", "BAR"]
+  $ ruby mixed_names.rb -z
+  ["--zzz", nil]
+  $ ruby mixed_names.rb -z BAZ
+  ["--zzz", "BAZ"]
+  $ ruby mixed_names.rb --zzz
+  ["--zzz", nil]
+  $ ruby mixed_names.rb --zzz BAT
+  ["--zzz", "BAT"]
 
 === Option Arguments
 
@@ -153,6 +207,10 @@ When an option is found, the given argument is yielded.
 
 Executions:
 
+  $ ruby required_argument.rb --help
+  Usage: required_argument [options]
+      -x, --xxx XXX                    Required argument via short name
+      -y, --y YYY                      Required argument via long name
   $ ruby required_argument.rb -x AAA
   ["--xxx", "AAA"]
   $ ruby required_argument.rb -y BBB
@@ -178,9 +236,23 @@ When an option with an argument is found, the given argument yielded.
 
 Executions:
 
+  $ ruby optional_argument.rb --help
+  Usage: optional_argument [options]
+      -x, --xxx [XXX]                  Optional argument via short  name
+      -y, --yyy [YYY]                  Optional argument via long name
   $ ruby optional_argument.rb -x AAA
   ["--xxx", "AAA"]
   $ ruby optional_argument.rb -y BBB
   ["--yyy", "BBB"]
 
 Omitting an optional argument does not raise an error.
+
+=== Argument Converters
+
+An option can specify that its argument is to be converted
+from the default \String to an instance of another class.
+
+There are a number of built-in converters.
+You can also define custom converters.
+
+See {Argument Converters}[./argument_converters_rdoc.html].