[ruby/optparse] Tutorial: explain custom argument converters (https://github.com/ruby/optparse/pull/19)

385dd4322d

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]
@@ -50,6 +51,42 @@ The class also has:
   - {Default Values for Options}[#label-Default+Values+for+Options]
 - {Argument Converters}[#label-Argument+Converters]
 
+=== 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
 
 A common way to define an option in \OptionParser
@@ -361,7 +398,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