[Python-checkins] python/dist/src/Doc/lib liboptparse.tex,1.3,1.4

2003年5月03日 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}