From: Andrew M. Kuchling <amk@amk.ca>
Date: Sat, 19 Jan 2008 21:00:38 +0000 (+0000)
Subject: Bug 1296: restore text describing OptionGroup
X-Git-Tag: v2.6a1~520
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=8b506e7a2d4e8cb6ffd6b7f2845e45aa92daa4d4;p=thirdparty%2FPython%2Fcpython.git

Bug 1296: restore text describing OptionGroup
---

diff --git a/Doc/library/optparse.rst b/Doc/library/optparse.rst
index e193eb850f4d..e5937b7abb15 100644
--- a/Doc/library/optparse.rst
+++ b/Doc/library/optparse.rst
@@ -539,6 +539,35 @@ help message:
   default value.  If an option has no default value (or the default value is
   ``None``), ``%default`` expands to ``none``.
 
+When dealing with many options, it is convenient to group these
+options for better help output.  An :class:`OptionParser` can contain
+several option groups, each of which can contain several options.
+
+Continuing with the parser defined above, adding an
+:class:`OptionGroup` to a parser is easy::
+
+    group = OptionGroup(parser, "Dangerous Options",
+			"Caution: use these options at your own risk.  "
+			"It is believed that some of them bite.")
+    group.add_option("-g", action="store_true", help="Group option.")
+    parser.add_option_group(group)
+
+This would result in the following help output::
+
+    usage:  [options] arg1 arg2
+
+    options:
+      -h, --help           show this help message and exit
+      -v, --verbose        make lots of noise [default]
+      -q, --quiet          be vewwy quiet (I'm hunting wabbits)
+      -fFILE, --file=FILE  write output to FILE
+      -mMODE, --mode=MODE  interaction mode: one of 'novice', 'intermediate'
+			   [default], 'expert'
+
+      Dangerous Options:
+	Caution: use of these options is at your own risk.  It is believed that
+	some of them bite.
+	-g                 Group option.
 
 .. _optparse-printing-version-string: