From af81c576ea441efb6c05aab31dc58b2792a5fdf2 Mon Sep 17 00:00:00 2001
From: "Andrew M. Kuchling" <amk@amk.ca>
Date: Sat, 19 Jan 2008 21:01:39 +0000
Subject: [PATCH] Bug 1296: restore text describing OptionGroup

---
 Doc/lib/liboptparse.tex | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/Doc/lib/liboptparse.tex b/Doc/lib/liboptparse.tex
index cd1fb00abde..0b476384398 100644
--- a/Doc/lib/liboptparse.tex
+++ b/Doc/lib/liboptparse.tex
@@ -558,6 +558,39 @@ default value is \code{None}), \code{{\%}default} expands to \code{none}.
 
 \end{itemize}
 
+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:
+
+\begin{verbatim}
+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)
+\end{verbatim}
+
+This would result in the following help output:
+
+\begin{verbatim}
+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.
+\end{verbatim}
 
 \subsubsection{Printing a version string\label{optparse-printing-version-string}}