More on tutorial (#23)

- Removed a largish block of repeated text.
- Added sections "Top List and Base List" and "Methods for Defining Options" (on, define, etc.).
- Linked from class OptionParser doc to the tutorial.

doc/optparse/ruby/basic.rb

@@ -12,5 +12,6 @@
 parser.on('-z', 'Whether to Z') do |value|
   p ['z', value]
 end
-# Parse the command line.
-parser.parse!
+# Parse the command line and return pared-down ARGV.
+p parser.parse!
+

doc/optparse/tutorial.rdoc

@@ -27,10 +27,7 @@ With \OptionParser, you can define options so that for each option:
 - The argument may be restricted to specified _forms_.
 - The argument may be restricted to specified _values_.
 
-The class also has:
-
-- Method #summarize: returns a text summary of the options.
-- Method #help: displays automatically-generated help text.
+The class also has method #help, which displays automatically-generated help text.
 
 === Contents
 
@@ -57,6 +54,8 @@ The class also has:
   - {Default Values for Options}[#label-Default+Values+for+Options]
 - {Argument Converters}[#label-Argument+Converters]
 - {Help}[#label-Help]
+- {Top List and Base List}[#label-Top+List+and+Base+List]
+- {Methods for Defining Options}[#label-Methods+for+Defining+Options]
 
 === To Begin With
 
@@ -83,16 +82,29 @@ From these defined options, the parser automatically builds help text:
 
 When an option is found during parsing,
 the block defined for the option is called with the argument value.
+An invalid option raises an exception.
+
+Method #parse!, which is used most often in this tutorial,
+removes from \ARGV the options and arguments it finds,
+leaving other non-option arguments for the program to handle on its own.
+The method returns the possibly-reduced \ARGV array.
 
 Executions:
 
   $ ruby basic.rb -x -z
   ["x", true]
   ["z", true]
+  []
   $ ruby basic.rb -z -y -x
   ["z", true]
   ["y", true]
   ["x", true]
+  []
+  $ ruby basic.rb -x input_file.txt output_file.txt
+  ["x", true]
+  ["input_file.txt", "output_file.txt"]
+  $ ruby basic.rb -a
+  basic.rb:16:in `<main>': invalid option: -a (OptionParser::InvalidOption)
 
 === Defining Options
 
@@ -151,11 +163,6 @@ Multiple short names can "share" a hyphen:
   ["-1 or -%", true]
   ["-1 or -%", true]
 
-This is a good time to note that giving an undefined option raises an exception:
-
-  $ ruby short_names.rb -z
-  short_names.rb:9:in `<main>': invalid option: -z (OptionParser::InvalidOption)
-
 ==== Long Option Names
 
 A long option name consists of two hyphens and a one or more characters
@@ -597,3 +604,57 @@ Execution:
     -z, --zzz [ZZZ]      Et magnis dis parturient montes, nascetur
                          ridiculus mus. Donec quam felis, ultricies
                          nec, pellentesque eu, pretium quis, sem.
+
+=== Top List and Base List
+
+An \OptionParser object maintains a stack of \OptionParser::List objects,
+each of which has a collection of zero or more options.
+It is unlikely that you'll need to add or take away from that stack.
+
+The stack includes:
+
+- The <em>top list</em>, given by \OptionParser#top.
+- The <em>base list</em>, given by \OptionParser#base.
+
+When \OptionParser builds its help text, the options in the top list
+precede those in the base list.
+
+=== Methods for Defining Options
+
+Option-defining methods allow you to create an option, and also append/prepend it
+to the top list or append it to the base list.
+
+Each of these next three methods accepts a sequence of parameter arguments and a block,
+creates an option object using method \Option#make_switch (see below),
+and returns the created option:
+
+- \Method \OptionParser#define appends the created option to the top list.
+
+- \Method \OptionParser#define_head prepends the created option to the top list.
+
+- \Method \OptionParser#define_tail appends the created option to the base list.
+
+These next three methods are identical to the three above,
+except for their return values:
+
+- \Method \OptionParser#on is identical to method \OptionParser#define,
+  except that it returns the parser object +self+.
+
+- \Method \OptionParser#on_head is identical to method \OptionParser#define_head,
+  except that it returns the parser object +self+.
+
+- \Method \OptionParser#on_tail is identical to method \OptionParser#define_tail,
+  except that it returns the parser object +self+.
+
+Though you may never need to call it directly,
+here's the core method for defining an option:
+
+- \Method \OptionParser#make_switch accepts an array of parameters and a block.
+  See {Parameters for New Options}[./option_params_rdoc.html].
+  This method is unlike others here in that it:
+  - Accepts an <em>array of parameters</em>;
+    others accept a <em>sequence of parameter arguments</em>.
+  - Returns an array containing the created option object,
+    option names, and other values;
+    others return either the created option object
+    or the parser object +self+.

lib/optparse.rb

@@ -48,6 +48,10 @@
 #
 # == OptionParser
 #
+# === New to \OptionParser?
+#
+# See the {Tutorial}[./doc/optparse/tutorial_rdoc.html].
+#
 # === Introduction
 #
 # OptionParser is a class for command-line option analysis.  It is much more
@@ -415,8 +419,10 @@
 #
 # === Further documentation
 #
-# The above examples should be enough to learn how to use this class.  If you
-# have any questions, file a ticket at http://bugs.ruby-lang.org.
+# The above examples, along with the accompanying
+# {Tutorial}[./doc/optparse/tutorial_rdoc.html],
+# should be enough to learn how to use this class.
+# If you have any questions, file a ticket at http://bugs.ruby-lang.org.
 #
 class OptionParser
   OptionParser::Version = "0.1.1"