[Python-checkins] python/dist/src/Doc/lib liboptparse.tex,1.5,1.6
gward@users.sourceforge.net
gward@users.sourceforge.net
Sat, 03 May 2003 13:41:39 -0700
Update of /cvsroot/python/python/dist/src/Doc/lib
In directory sc8-pr-cvs1:/tmp/cvs-serv23012
Modified Files:
liboptparse.tex
Log Message:
Rename "The Tao of Option Parsing" section to "Philosophy".
Remove first-person usage from it. Various wording tweaks.
Index: liboptparse.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/liboptparse.tex,v
retrieving revision 1.5
retrieving revision 1.6
diff -C2 -d -r1.5 -r1.6
*** liboptparse.tex 3 May 2003 20:13:08 -0000 1.5
--- liboptparse.tex 3 May 2003 20:41:37 -0000 1.6
***************
*** 66,78 ****
parsing your command-line.
! \subsection{The Tao of Option Parsing\label{optparse-tao}}
! \module{optparse} is an implementation of what I have always
! considered the most obvious, straightforward, and user-friendly way to
! design a user interface for command-line programs. In short, I have
! fairly firm ideas of the Right Way (and the many Wrong Ways) to do
! argument parsing, and \module{optparse} reflects many of those ideas.
! This section is meant to explain this philosophy, which in turn is
! heavily influenced by the \UNIX{} and GNU toolkits.
\subsubsection{Terminology\label{optparse-terminology}}
--- 66,76 ----
parsing your command-line.
! \subsection{Philosophy\label{optparse-philosophy}}
! The purpose of \module{optparse} is to make it very easy to provide the
! most standard, obvious, straightforward, and user-friendly user
! interface for \UNIX{} command-line programs. The \module{optparse}
! philosophy is heavily influenced by the \UNIX{} and GNU toolkits, and
! this section is meant to explain that philosophy.
\subsubsection{Terminology\label{optparse-terminology}}
***************
*** 89,94 ****
important.) \UNIX{} shells also use the term ``word''.
! It's occasionally desirable to substitute an argument list other
! than \var{sys.argv[1:]}, so you should read ``argument'' as ``an element of
\var{sys.argv[1:]}, or of some other list provided as a substitute for
\var{sys.argv[1:]}''.
--- 87,92 ----
important.) \UNIX{} shells also use the term ``word''.
! It is occasionally desirable to use an argument list other than
! \var{sys.argv[1:]}, so you should read ``argument'' as ``an element of
\var{sys.argv[1:]}, or of some other list provided as a substitute for
\var{sys.argv[1:]}''.
***************
*** 121,131 ****
\end{itemize}
! These option syntaxes are not supported by \module{optparse}, and they
! never will be. (If you really want to use one of those option
! syntaxes, you'll have to subclass OptionParser and override all the
! difficult bits. But please don't! \module{optparse} does things the
! traditional \UNIX/GNU way deliberately; the first three are
! non-standard anywhere, and the last one makes sense only if you're
! exclusively targeting MS-DOS/Windows and/or VMS.)
\term{option argument}
--- 119,129 ----
\end{itemize}
! \module{optparse} does not support these option syntaxes, and it never
! will. (If you really want to use one of those option syntaxes, you'll
! have to subclass \class{OptionParser} and override all the difficult
! bits. But please don't! \module{optparse} does things the traditional
! \UNIX/GNU way deliberately; the first three are non-standard anywhere,
! and the last one makes sense only if you're exclusively targeting
! MS-DOS/Windows and/or VMS.)
\term{option argument}
***************
*** 151,170 ****
meaning that some options will take an argument if they see it, and
won't if they don't. This is somewhat controversial, because it makes
! parsing ambiguous: if \programopt{-a} takes an optional argument and
! \programopt{-b} is another option entirely, how do we interpret
! \programopt{-ab}? \module{optparse} does not currently support this.
\term{positional argument}
something leftover in the argument list after options have been
! parsed, ie. after options and their arguments have been parsed and
removed from the argument list.
\term{required option}
! an option that must be supplied on the command-line; the phrase
! ``required option'' is an oxymoron and is usually considered poor UI
! design. \module{optparse} doesn't prevent you from implementing
! required options, but doesn't give you much help with it either. See
! ``Extending Examples'' (section~\ref{optparse-extending-examples}) for
! two ways to implement required options with \module{optparse}.
\end{definitions}
--- 149,170 ----
meaning that some options will take an argument if they see it, and
won't if they don't. This is somewhat controversial, because it makes
! parsing ambiguous: if \programopt{-a} and \programopt{-b} are both
! options, and \programopt{-a} takes an optional argument, how do we
! interpret \programopt{-ab}? \module{optparse} does not support optional
! option arguments.
\term{positional argument}
something leftover in the argument list after options have been
! parsed, i.e., after options and their arguments have been parsed and
removed from the argument list.
\term{required option}
! an option that must be supplied on the command-line. The phrase
! ``required option'' is an oxymoron; the presence of ``required options''
! in a program is usually a sign of careless user interface design.
! \module{optparse} doesn't prevent you from implementing required
! options, but doesn't give you much help with it either. See ``Extending
! Examples'' (section~\ref{optparse-extending-examples}) for two ways to
! implement required options with \module{optparse}.
\end{definitions}
***************
*** 178,188 ****
\programopt{-v} and \longprogramopt{report} are both options. Assuming
the \longprogramopt{report} option takes one argument,
! ``/tmp/report.txt'' is an option argument. ``foo'' and ``bar'' are
! positional arguments.
\subsubsection{What are options for?\label{optparse-options}}
Options are used to provide extra information to tune or customize the
! execution of a program. In case it wasn't clear, options are usually
\emph{optional}. A program should be able to run just fine with no
options whatsoever. (Pick a random program from the \UNIX{} or GNU
--- 178,188 ----
\programopt{-v} and \longprogramopt{report} are both options. Assuming
the \longprogramopt{report} option takes one argument,
! \code{/tmp/report.txt} is an option argument. \code{foo} and \code{bar}
! are positional arguments.
\subsubsection{What are options for?\label{optparse-options}}
Options are used to provide extra information to tune or customize the
! execution of a program. In case it wasn't clear, options should be
\emph{optional}. A program should be able to run just fine with no
options whatsoever. (Pick a random program from the \UNIX{} or GNU