https://git.ruby-lang.org/ruby.git/commit/?id=fe72cff487

From fe72cff487283dbaadb9757e74f00291d772cb6f Mon Sep 17 00:00:00 2001
From: Burdette Lamar <BurdetteLamar@Y...>
Date: Tue, 6 Apr 2021 13:55:21 -0500
Subject: [ruby/optparse] More on tutorial (#9)

* More on tutorial: clearer example output

https://github.com/ruby/optparse/commit/84dfd92d2a
---
 doc/ruby/argv.rb                  |   2 -
 doc/ruby/long_names.rb            |   9 --
 doc/ruby/mixed_names.rb           |   9 --
 doc/ruby/short_names.rb           |   9 --
 doc/tutorial.rdoc                 | 125 -------------------------
 doc/tutorial/argv.rb              |   2 +
 doc/tutorial/long_names.rb        |   9 ++
 doc/tutorial/mixed_names.rb       |   9 ++
 doc/tutorial/optional_argument.rb |   9 ++
 doc/tutorial/required_argument.rb |   9 ++
 doc/tutorial/short_names.rb       |   9 ++
 doc/tutorial/tutorial.rdoc        | 186 ++++++++++++++++++++++++++++++++++++++
 12 files changed, 233 insertions(+), 154 deletions(-)
 delete mode 100644 doc/ruby/argv.rb
 delete mode 100644 doc/ruby/long_names.rb
 delete mode 100644 doc/ruby/mixed_names.rb
 delete mode 100644 doc/ruby/short_names.rb
 delete mode 100644 doc/tutorial.rdoc
 create mode 100644 doc/tutorial/argv.rb
 create mode 100644 doc/tutorial/long_names.rb
 create mode 100644 doc/tutorial/mixed_names.rb
 create mode 100644 doc/tutorial/optional_argument.rb
 create mode 100644 doc/tutorial/required_argument.rb
 create mode 100644 doc/tutorial/short_names.rb
 create mode 100644 doc/tutorial/tutorial.rdoc

diff --git a/doc/ruby/argv.rb b/doc/ruby/argv.rb
deleted file mode 100644
index 12495cf..0000000
--- a/doc/ruby/argv.rb
+++ /dev/null
@@ -1,2 +0,0 @@ https://github.com/ruby/ruby/blob/trunk/#L0
-p ARGV
-
diff --git a/doc/ruby/long_names.rb b/doc/ruby/long_names.rb
deleted file mode 100644
index e36152d..0000000
--- a/doc/ruby/long_names.rb
+++ /dev/null
@@ -1,9 +0,0 @@ https://github.com/ruby/ruby/blob/trunk/#L0
-require 'optparse'
-parser = OptionParser.new
-parser.on('--xxx') do |option|
-  p "--xxx #{option}"
-end
-parser.on('--y1%', '--z2#') do |option|
-  p "--y1% or --z2# #{option}"
-end
-parser.parse!
diff --git a/doc/ruby/mixed_names.rb b/doc/ruby/mixed_names.rb
deleted file mode 100644
index b8f3ac9..0000000
--- a/doc/ruby/mixed_names.rb
+++ /dev/null
@@ -1,9 +0,0 @@ https://github.com/ruby/ruby/blob/trunk/#L0
-require 'optparse'
-parser = OptionParser.new
-parser.on('-x', '--xxx') do |option|
-  p "--xxx #{option}"
-end
-parser.on('-y', '--y1%') do |option|
-  p "--y1% #{option}"
-end
-parser.parse!
diff --git a/doc/ruby/short_names.rb b/doc/ruby/short_names.rb
deleted file mode 100644
index 0dc35b7..0000000
--- a/doc/ruby/short_names.rb
+++ /dev/null
@@ -1,9 +0,0 @@ https://github.com/ruby/ruby/blob/trunk/#L0
-require 'optparse'
-parser = OptionParser.new
-parser.on('-x') do |option|
-  p "-x #{option}"
-end
-parser.on('-1', '-%') do |option|
-  p "-1 or -% #{option}"
-end
-parser.parse!
diff --git a/doc/tutorial.rdoc b/doc/tutorial.rdoc
deleted file mode 100644
index 3f60b46..0000000
--- a/doc/tutorial.rdoc
+++ /dev/null
@@ -1,125 +0,0 @@ https://github.com/ruby/ruby/blob/trunk/#L0
-== Tutorial
-
-=== Why OptionParser?
-
-When a Ruby program executes, it captures its command-line arguments
-and options into variable ARGV.
-This simple program just prints its \ARGV:
-
-  :include: ruby/argv.rb
-
-Execution, with arguments and options:
-
-  $ ruby doc/ruby/argv.rb foo --bar --baz bat bam
-  ["foo", "--bar", "--baz", "bat", "bam"]
-
-The executing program is responsible for parsing and handling
-the command-line options.
-
-OptionParser offers methods for parsing and handling those options.
-
-With \OptionParser, you can define options so that for each option:
-
-- The code that defines the option and code that handles that option
-  are in the same place.
-- The option may take no argument, a required argument, or an optional argument.
-- The argument may be automatically converted to a specified class.
-- The argument may be restricted to specified _forms_.
-- The argument may be restricted to specified _values_.
-
-The class also has a method #summarize that returns a string summary
-of all defined options.
-
-=== Defining Options
-
-A common way to define an option in \OptionParser
-is with instance method OptionParser#on.
-
-The method may be called with any number of arguments
-(whose order does not matter),
-and may also have a trailing optional keyword argument +into+.
-
-The given arguments determine the characteristics of the new option.
-These may include:
-
-- One or more short option names.
-- One or more long option names.
-- Whether the option takes no argument, an optional argument, or a required argument.
-- Acceptable _forms_ for the argument.
-- Acceptable _values_ for the argument.
-- A proc or method to be called when the parser encounters the option.
-- String descriptions for the option.
-
-=== Option Names
-
-You can give an option one or more names of two types:
-
-- Short (1-character) name, beginning with one hyphen (<tt>-</tt>).
-- Long (multi-character) name, beginning with two hyphens (<tt>--</tt>).
-
-==== Short Option Names
-
-A short option name consists of a hyphen and a single character.
-
-File +short_names.rb+
-defines an option with a short name, <tt>-x</tt>,
-and an option with two short names (aliases, in effect) <tt>-y</tt> and <tt>-z</tt>.
-
-  :include: ruby/short_names.rb
-
-Executions:
-
-  $ ruby doc/ruby/short_names.rb -x
-  "-x true"
-  $ ruby doc/ruby/short_names.rb -1
-  "-1 or -% true"
-  $ ruby doc/ruby/short_names.rb -%
-  "-1 or -% true"
-
-Multiple short names can "share" a hyphen:
-
-  $ ruby short_names.rb -x1%
-  "-x true"
-  "-1 or -% true"
-  "-1 or -% true"
-
-==== Long Option Names
-
-A long option name consists of two hyphens and a one or more characters
-(usually two or more characters).
-
-File +long_names.rb+
-defines an option with a long name, <tt>--xxx</tt>,
-and an option with two long names (aliases, in effect) <tt>--y1%</tt> and <tt>--z2#</tt>.
-
-  :include: ruby/long_names.rb
-
-Executions:
-
-  $ ruby long_names.rb --xxx
-  "--xxx true"
-  $ ruby long_names.rb --y1%
-  "--y1% or -z2# true"
-  $ ruby long_names.rb --z2#
-  "--y1% or -z2# true"
-
-==== Mixing Option Names
-
-Many developers like to mix short and long option names,
-so that a short name is in effect an abbreviation of a long name.
-
-File +mixed_names.rb+
-defines options that each have both a short and a long name.
-
-  :include: ruby/mixed_names.rb
-
-Executions:
-
-  $ ruby doc/ruby/mixed_names.rb -x
-  "--xxx true"
-  $ ruby doc/ruby/mixed_names.rb --xxx
-  "--xxx true"
-  $ ruby doc/ruby/mixed_names.rb -y
-  "--y1% true"
-  $ ruby doc/ruby/mixed_names.rb --y1%
-  "--y1% true"
diff --git a/doc/tutorial/argv.rb b/doc/tutorial/argv.rb
new file mode 100644
index 0000000..12495cf
--- /dev/null
+++ b/doc/tutorial/argv.rb
@@ -0,0 +1,2 @@ https://github.com/ruby/ruby/blob/trunk/doc/tutorial/argv.rb#L1
+p ARGV
+
diff --git a/doc/tutorial/long_names.rb b/doc/tutorial/long_names.rb
new file mode 100644
index 0000000..a34b338
--- /dev/null
+++ b/doc/tutorial/long_names.rb
@@ -0,0 +1,9 @@ https://github.com/ruby/ruby/blob/trunk/doc/tutorial/long_names.rb#L1
+require 'optparse'
+parser = OptionParser.new
+parser.on('--xxx') do |value|
+  p ['-xxx', value]
+end
+parser.on('--y1%', '--z2#') do |value|
+  p ['--y1% or --z2#', value]
+end
+parser.parse!
diff --git a/doc/tutorial/mixed_names.rb b/doc/tutorial/mixed_names.rb
new file mode 100644
index 0000000..e886049
--- /dev/null
+++ b/doc/tutorial/mixed_names.rb
@@ -0,0 +1,9 @@ https://github.com/ruby/ruby/blob/trunk/doc/tutorial/mixed_names.rb#L1
+require 'optparse'
+parser = OptionParser.new
+parser.on('-x', '--xxx') do |value|
+  p ['--xxx', value]
+end
+parser.on('-y', '--y1%') do |value|
+  p ['--y1%', value]
+end
+parser.parse!
diff --git a/doc/tutorial/optional_argument.rb b/doc/tutorial/optional_argument.rb
new file mode 100644
index 0000000..ebff2f4
--- /dev/null
+++ b/doc/tutorial/optional_argument.rb
@@ -0,0 +1,9 @@ https://github.com/ruby/ruby/blob/trunk/doc/tutorial/optional_argument.rb#L1
+require 'optparse'
+parser = OptionParser.new
+parser.on('-x [XXX]', '--xxx') do |value|
+  p ['--xxx', value]
+end
+parser.on('-y', '--yyy [YYY]') do |value|
+  p ['--yyy', value]
+end
+parser.parse!
diff --git a/doc/tutorial/required_argument.rb b/doc/tutorial/required_argument.rb
new file mode 100644
index 0000000..7a5a868
--- /dev/null
+++ b/doc/tutorial/required_argument.rb
@@ -0,0 +1,9 @@ https://github.com/ruby/ruby/blob/trunk/doc/tutorial/required_argument.rb#L1
+require 'optparse'
+parser = OptionParser.new
+parser.on('-x XXX', '--xxx') do |value|
+  p ['--xxx', value]
+end
+parser.on('-y', '--y YYY') do |value|
+  p ['--yyy', value]
+end
+parser.parse!
diff --git a/doc/tutorial/short_names.rb b/doc/tutorial/short_names.rb
new file mode 100644
index 0000000..6581dfe
--- /dev/null
+++ b/doc/tutorial/short_names.rb
@@ -0,0 +1,9 @@ https://github.com/ruby/ruby/blob/trunk/doc/tutorial/short_names.rb#L1
+require 'optparse'
+parser = OptionParser.new
+parser.on('-x') do |value|
+  p ['x', value]
+end
+parser.on('-1', '-%') do |value|
+  p ['-1 or -%', value]
+end
+parser.parse!
diff --git a/doc/tutorial/tutorial.rdoc b/doc/tutorial/tutorial.rdoc
new file mode 100644
index 0000000..60ead0a
--- /dev/null
+++ b/doc/tutorial/tutorial.rdoc
@@ -0,0 +1,186 @@ https://github.com/ruby/ruby/blob/trunk/doc/tutorial/tutorial.rdoc#L1
+== Tutorial
+
+=== Why OptionParser?
+
+When a Ruby program executes, it captures its command-line arguments
+and options into variable ARGV.
+This simple program just prints its \ARGV:
+
+  :include: argv.rb
+
+Execution, with arguments and options:
+
+  $ ruby argv.rb foo --bar --baz bat bam
+  ["foo", "--bar", "--baz", "bat", "bam"]
+
+The executing program is responsible for parsing and handling
+the command-line options.
+
+OptionParser offers methods for parsing and handling those options.
+
+With \OptionParser, you can define options so th (... truncated)

--
ML: ruby-changes@q...
Info: http://www.atdot.net/~ko1/quickml/