[Python-checkins] python/dist/src/Doc/lib liboptparse.tex,1.3,1.4
gward@users.sourceforge.net
gward@users.sourceforge.net
Sat, 03 May 2003 12:41:47 -0700
Update of /cvsroot/python/python/dist/src/Doc/lib
In directory sc8-pr-cvs1:/tmp/cvs-serv27231
Modified Files:
liboptparse.tex
Log Message:
Use TeX quotes -- ``foo'' -- as appropriate.
Remove whitespace around em-dashes.
Index: liboptparse.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/liboptparse.tex,v
retrieving revision 1.3
retrieving revision 1.4
diff -C2 -d -r1.3 -r1.4
*** liboptparse.tex 3 May 2003 19:16:36 -0000 1.3
--- liboptparse.tex 3 May 2003 19:41:45 -0000 1.4
***************
*** 34,38 ****
With these few lines of code, users of your script can now do the
! "usual thing" on the command-line:
\begin{verbatim}
--- 34,38 ----
With these few lines of code, users of your script can now do the
! ``usual thing'' on the command-line:
\begin{verbatim}
***************
*** 189,193 ****
toolsets. Can it run without any options at all and still make sense?
The only exceptions I can think of are \program{find}, \program{tar},
! and \program{dd} --- all of which are mutant oddballs that have been
rightly criticized for their non-standard syntax and confusing
interfaces.)
--- 189,193 ----
toolsets. Can it run without any options at all and still make sense?
The only exceptions I can think of are \program{find}, \program{tar},
! and \program{dd}---all of which are mutant oddballs that have been
rightly criticized for their non-standard syntax and confusing
interfaces.)
***************
*** 229,233 ****
possible. If your program requires 17 distinct pieces of information in
order to run successfully, it doesn't much matter \emph{how} you get that
! information from the user --- most people will give up and walk away
before they successfully run the program. This applies whether the user
interface is a command-line, a configuration file, a GUI, or whatever:
--- 229,233 ----
possible. If your program requires 17 distinct pieces of information in
order to run successfully, it doesn't much matter \emph{how} you get that
! information from the user---most people will give up and walk away
before they successfully run the program. This applies whether the user
interface is a command-line, a configuration file, a GUI, or whatever:
***************
*** 236,244 ****
In short, try to minimize the amount of information that users are
! absolutely required to supply --- use sensible defaults whenever
possible. Of course, you also want to make your programs reasonably
flexible. That's what options are for. Again, it doesn't matter if
they are entries in a config file, checkboxes in the ``Preferences''
! dialog of a GUI, or command-line options --- the more options you
implement, the more flexible your program is, and the more complicated
its implementation becomes. It's quite easy to overwhelm users (and
--- 236,244 ----
In short, try to minimize the amount of information that users are
! absolutely required to supply---use sensible defaults whenever
possible. Of course, you also want to make your programs reasonably
flexible. That's what options are for. Again, it doesn't matter if
they are entries in a config file, checkboxes in the ``Preferences''
! dialog of a GUI, or command-line options---the more options you
implement, the more flexible your program is, and the more complicated
its implementation becomes. It's quite easy to overwhelm users (and
***************
*** 282,286 ****
\var{help}.
! \subsubsection{The "store" action\label{optparse-store-action}}
The action tells \module{optparse} what to do when it sees one of the
--- 282,286 ----
\var{help}.
! \subsubsection{The \var{store} action\label{optparse-store-action}}
The action tells \module{optparse} what to do when it sees one of the
***************
*** 290,294 ****
store it to your chosen destination.
! For example, let's fill in the "..." of that last option:
\begin{verbatim}
--- 290,294 ----
store it to your chosen destination.
! For example, let's fill in the ``...'' of that last option:
\begin{verbatim}
***************
*** 309,313 ****
When \module{optparse} sees the \programopt{-f}, it sucks in the next
! argument --- ``foo.txt'' --- and stores it in the \var{filename}
attribute of a special object. That object is the first return value
from \function{parse_args()}, so:
--- 309,313 ----
When \module{optparse} sees the \programopt{-f}, it sucks in the next
! argument---\code{foo.txt}---and stores it in the \var{filename}
attribute of a special object. That object is the first return value
from \function{parse_args()}, so:
***************
*** 317,324 ****
\end{verbatim}
! will print ``foo.txt''.
! Other option types supported by \module{optparse} are ``int'' and
! ``float''. Here's an option that expects an integer argument:
\begin{verbatim}
--- 317,324 ----
\end{verbatim}
! will print \code{foo.txt}.
! Other option types supported by \module{optparse} are \code{int} and
! \code{float}. Here's an option that expects an integer argument:
\begin{verbatim}
***************
*** 327,334 ****
Note that I didn't supply a long option, which is perfectly acceptable.
! I also didn't specify the action --- it defaults to ``store''.
Let's parse another fake command-line. This time, we'll jam the
! option argument right up against the option --- \programopt{-n42} (one
argument) is equivalent to \programopt{-n 42} (two arguments). :
--- 327,334 ----
Note that I didn't supply a long option, which is perfectly acceptable.
! I also didn't specify the action---it defaults to ``store''.
Let's parse another fake command-line. This time, we'll jam the
! option argument right up against the option---\programopt{-n42} (one
argument) is equivalent to \programopt{-n 42} (two arguments). :
***************
*** 360,367 ****
section~\ref{optparse-adding-types}, ``Adding new types.''
! \subsubsection{Other "store_*" actions\label{optparse-other-store-actions}}
! Flag options --- set a variable to true or false when a particular
! option is seen --- are quite common. \module{optparse} supports them
with two separate actions, ``store_true'' and ``store_false''. For
example, you might have a \var{verbose} flag that is turned on with
--- 360,367 ----
section~\ref{optparse-adding-types}, ``Adding new types.''
! \subsubsection{Other \var{store_*} actions\label{optparse-other-store-actions}}
! Flag options---set a variable to true or false when a particular
! option is seen---are quite common. \module{optparse} supports them
with two separate actions, ``store_true'' and ``store_false''. For
example, you might have a \var{verbose} flag that is turned on with
***************
*** 375,379 ****
Here we have two different options with the same destination, which is
perfectly OK. (It just means you have to be a bit careful when setting
! default values --- see below.)
When \module{optparse} sees \programopt{-v} on the command line, it
--- 375,379 ----
Here we have two different options with the same destination, which is
perfectly OK. (It just means you have to be a bit careful when setting
! default values---see below.)
When \module{optparse} sees \programopt{-v} on the command line, it
***************
*** 475,488 ****
\end{verbatim}
! \module{optparse} expands "\%prog" in the usage string to the name of the
current script, ie. \code{os.path.basename(sys.argv[0])}. The
expanded string is then printed before the detailed option help.
If you don't supply a usage string, \module{optparse} uses a bland but
! sensible default: ``usage: \%prog [options]'', which is fine if your
script doesn't take any positional arguments.
\item every option defines a help string, and doesn't worry about
! line-wrapping --- \module{optparse} takes care of wrapping lines and
making the help output look good.
--- 475,488 ----
\end{verbatim}
! \module{optparse} expands \samp{\%prog} in the usage string to the name of the
current script, ie. \code{os.path.basename(sys.argv[0])}. The
expanded string is then printed before the detailed option help.
If you don't supply a usage string, \module{optparse} uses a bland but
! sensible default: \code{"usage: \%prog [options]"}, which is fine if your
script doesn't take any positional arguments.
\item every option defines a help string, and doesn't worry about
! line-wrapping---\module{optparse} takes care of wrapping lines and
making the help output look good.
***************
*** 498,502 ****
\programopt{-m}/\longprogramopt{mode}. By default, \module{optparse}
converts the destination variable name to uppercase and uses that for
! the meta-variable. Sometimes, that's not what you want --- for
example, the \var{filename} option explicitly sets
\code{metavar="FILE"}, resulting in this automatically-generated
--- 498,502 ----
\programopt{-m}/\longprogramopt{mode}. By default, \module{optparse}
converts the destination variable name to uppercase and uses that for
! the meta-variable. Sometimes, that's not what you want---for
example, the \var{filename} option explicitly sets
\code{metavar="FILE"}, resulting in this automatically-generated
***************
*** 579,583 ****
The one thing you need to know for basic usage is how
\module{optparse} behaves when it encounters an error on the
! command-line --- e.g. \programopt{-n4x} where \programopt{-n} is an
integer-valued option. \module{optparse} prints your usage message to
stderr, followed by a useful and human-readable error message. Then
--- 579,583 ----
The one thing you need to know for basic usage is how
\module{optparse} behaves when it encounters an error on the
! command-line---e.g. \programopt{-n4x} where \programopt{-n} is an
integer-valued option. \module{optparse} prints your usage message to
stderr, followed by a useful and human-readable error message. Then
***************
*** 674,678 ****
This method makes it easier to track down exceptions raised by the
\class{Option} constructor, which are common because of the complicated
! interdependencies among the various keyword arguments --- if you get it
wrong, \module{optparse} raises \exception{OptionError}.
--- 674,678 ----
This method makes it easier to track down exceptions raised by the
\class{Option} constructor, which are common because of the complicated
! interdependencies among the various keyword arguments---if you get it
wrong, \module{optparse} raises \exception{OptionError}.
***************
*** 1085,1089 ****
raises an exception (\exception{OptionConflictError}) by default when
this happens. Since this is an easily-fixed programming error, you
! shouldn't try to catch this exception --- fix your mistake and get on
with life.
--- 1085,1089 ----
raises an exception (\exception{OptionConflictError}) by default when
this happens. Since this is an easily-fixed programming error, you
! shouldn't try to catch this exception---fix your mistake and get on
with life.
***************
*** 1186,1190 ****
\end{verbatim}
! Note that you supply a function object here --- so you must have
already defined a function \function{my_callback()} when you define
the callback option. In this simple case, \module{optparse} knows
--- 1186,1190 ----
\end{verbatim}
! Note that you supply a function object here---so you must have
already defined a function \function{my_callback()} when you define
the callback option. In this simple case, \module{optparse} knows
***************
*** 1238,1242 ****
is the option string seen on the command-line that's triggering the
callback. (If an abbreviated long option was used, \var{opt} will be
! the full, canonical option string --- e.g. if the user puts
\longprogramopt{foo} on the command-line as an abbreviation for
\longprogramopt{foobar}, then \var{opt} will be
--- 1238,1242 ----
is the option string seen on the command-line that's triggering the
callback. (If an abbreviated long option was used, \var{opt} will be
! the full, canonical option string---e.g. if the user puts
\longprogramopt{foo} on the command-line as an abbreviation for
\longprogramopt{foobar}, then \var{opt} will be
***************
*** 1349,1353 ****
\end{verbatim}
! Of course, you could put any condition in there --- you're not limited
to checking the values of already-defined options. For example, if
you have options that should not be called when the moon is full, all
--- 1349,1353 ----
\end{verbatim}
! Of course, you could put any condition in there---you're not limited
to checking the values of already-defined options. For example, if
you have options that should not be called when the moon is full, all
***************
*** 1364,1368 ****
\end{verbatim}
! (The definition of is_full_moon() is left as an exercise for the
reader.)
--- 1364,1368 ----
\end{verbatim}
! (The definition of \code{is_full_moon()} is left as an exercise for the
reader.)
***************
*** 1568,1585 ****
\begin{definitions}
! \term{"store" actions}
actions that result in \module{optparse} storing a value to an attribute
! of the OptionValues instance; these options require a 'dest'
attribute to be supplied to the Option constructor
! \term{"typed" actions}
actions that take a value from the command line and expect it to be
of a certain type; or rather, a string that can be converted to a
! certain type. These options require a 'type' attribute to the
Option constructor.
\end{definitions}
! Some default ``store'' actions are ``store'', ``store_const'',
! ``append'', and ``count''. The default ``typed'' actions are
! ``store'', ``append'', and ``callback''.
When you add an action, you need to decide if it's a ``store'' action,
--- 1568,1585 ----
\begin{definitions}
! \term{``store'' actions}
actions that result in \module{optparse} storing a value to an attribute
! of the OptionValues instance; these options require a \var{dest}
attribute to be supplied to the Option constructor
! \term{``typed'' actions}
actions that take a value from the command line and expect it to be
of a certain type; or rather, a string that can be converted to a
! certain type. These options require a \var{type} attribute to the
Option constructor.
\end{definitions}
! Some default ``store'' actions are \var{store}, \var{store_const},
! \var{append}, and \var{count}. The default ``typed'' actions are
! \var{store}, \var{append}, and \var{callback}.
When you add an action, you need to decide if it's a ``store'' action,
***************
*** 1591,1598 ****
\end{memberdesc}
\begin{memberdesc}{STORE_ACTIONS}
! "store" actions are additionally listed here.
\end{memberdesc}
\begin{memberdesc}{TYPED_ACTIONS}
! "typed" actions are additionally listed here.
\end{memberdesc}
--- 1591,1598 ----
\end{memberdesc}
\begin{memberdesc}{STORE_ACTIONS}
! ``store'' actions are additionally listed here.
\end{memberdesc}
\begin{memberdesc}{TYPED_ACTIONS}
! ``typed'' actions are additionally listed here.
\end{memberdesc}
***************
*** 1689,1694 ****
\begin{enumerate}
\item subclass OptionParser and override the error() method
! \item subclass Option and override the take_action() method --- you'll
! need to provide your own handling of the "help" action that
doesn't call sys.exit()
\end{enumerate}
--- 1689,1694 ----
\begin{enumerate}
\item subclass OptionParser and override the error() method
! \item subclass Option and override the take_action() method---you'll
! need to provide your own handling of the ``help'' action that
doesn't call sys.exit()
\end{enumerate}