From ed514946666b6cba0ecef03b2adc96d0cd1d14e9 Mon Sep 17 00:00:00 2001 From: Fred Drake Date: Fri, 6 Jul 2001 17:28:39 +0000 Subject: Fix up a few style nits -- avoid "e.g." and "i.e." -- these make translation more difficult, as well as reading the English more difficult for non-native speakers. --- Doc/tut/tut.tex | 120 +++++++++++++++++++++++++++++--------------------------- 1 file changed, 62 insertions(+), 58 deletions(-) diff --git a/Doc/tut/tut.tex b/Doc/tut/tut.tex index 25bdd08..8d75ff6 100644 --- a/Doc/tut/tut.tex +++ b/Doc/tut/tut.tex @@ -242,7 +242,7 @@ with the \emph{primary prompt}, usually three greater-than signs (\samp{>\code{>}>~}); for continuation lines it prompts with the \emph{secondary prompt}, by default three dots (\samp{...~}). The interpreter prints a welcome message stating its version number -and a copyright notice before printing the first prompt, e.g.: +and a copyright notice before printing the first prompt: \begin{verbatim} python @@ -325,8 +325,8 @@ You can also change the prompts \code{sys.ps1} and \code{sys.ps2} in this file. If you want to read an additional start-up file from the current -directory, you can program this in the global start-up file, -e.g.\ \samp{if os.path.isfile('.pythonrc.py'): +directory, you can program this in the global start-up file using code +like \samp{if os.path.isfile('.pythonrc.py'): execfile('.pythonrc.py')}. If you want to use the startup file in a script, you must do this explicitly in the script: @@ -527,7 +527,7 @@ double quotes: \end{verbatim} String literals can span multiple lines in several ways. Newlines can -be escaped with backslashes, e.g.: +be escaped with backslashes: \begin{verbatim} hello = "This is a rather long string containing\n\ @@ -728,7 +728,7 @@ The slice from \var{i} to \var{j} consists of all characters between the edges labeled \var{i} and \var{j}, respectively. For non-negative indices, the length of a slice is the difference of -the indices, if both are within bounds, e.g., the length of +the indices, if both are within bounds. For example, the length of \code{word[1:3]} is 2. The built-in function \function{len()} returns the length of a string: @@ -799,8 +799,8 @@ u'Hello World !' u'Hello\\\\u0020World !' \end{verbatim} -The raw mode is most useful when you have to enter lots of backslashes -e.g. in regular expressions. +The raw mode is most useful when you have to enter lots of +backslashes, as can be necessary in regular expressions. Apart from these standard encodings, Python provides a whole set of other ways of creating Unicode strings on the basis of a known @@ -1073,7 +1073,7 @@ iterating over an arithmetic progression of numbers (like in Pascal), or giving the user the ability to define both the iteration step and halting condition (as C), Python's \keyword{for}\stindex{for} statement iterates over the items of any -sequence (e.g., a list or a string), in the order that they appear in +sequence (a list or a string), in the order that they appear in the sequence. For example (no pun intended): % One suggestion was to give a real C example here, but that may only % serve to confuse non-C programmers. @@ -1090,10 +1090,10 @@ defenestrate 12 \end{verbatim} It is not safe to modify the sequence being iterated over in the loop -(this can only happen for mutable sequence types, i.e., lists). If -you need to modify the list you are iterating over, e.g., duplicate -selected items, you must iterate over a copy. The slice notation -makes this particularly convenient: +(this can only happen for mutable sequence types, such as lists). If +you need to modify the list you are iterating over (for example, to +duplicate selected items) you must iterate over a copy. The slice +notation makes this particularly convenient: \begin{verbatim} >>> for x in a[:]: # make a slice copy of the entire list @@ -1108,7 +1108,7 @@ makes this particularly convenient: If you do need to iterate over a sequence of numbers, the built-in function \function{range()} comes in handy. It generates lists -containing arithmetic progressions, e.g.: +containing arithmetic progressions: \begin{verbatim} >>> range(10) @@ -1245,7 +1245,7 @@ arguments are passed using \emph{call by value} (where the the object).\footnote{ Actually, \emph{call by object reference} would be a better description, since if a mutable object is passed, the caller - will see any changes the callee makes to it (e.g., items + will see any changes the callee makes to it (items inserted into a list). } When a function calls another function, a new local symbol table is created for that call. @@ -1331,7 +1331,7 @@ arguments. There are three forms, which can be combined. The most useful form is to specify a default value for one or more arguments. This creates a function that can be called with fewer -arguments than it is defined, e.g. +arguments than it is defined \begin{verbatim} def ask_ok(prompt, retries=4, complaint='Yes or no, please!'): @@ -1349,7 +1349,7 @@ This function can be called either like this: \code{ask_ok('OK to overwrite the file?', 2)}. The default values are evaluated at the point of function definition -in the \emph{defining} scope, so that e.g. +in the \emph{defining} scope, so that \begin{verbatim} i = 5 @@ -1509,7 +1509,7 @@ objects are required. They are syntactically restricted to a single expression. Semantically, they are just syntactic sugar for a normal function definition. Like nested function definitions, lambda forms cannot reference variables from the containing scope, but this can be -overcome through the judicious use of default argument values, e.g. +overcome through the judicious use of default argument values: \begin{verbatim} >>> def make_incrementor(n): @@ -1853,7 +1853,7 @@ another value is assigned to it). We'll find other uses for \section{Tuples and Sequences \label{tuples}} -We saw that lists and strings have many common properties, e.g., +We saw that lists and strings have many common properties, such as indexing and slicing operations. They are two examples of \emph{sequence} data types. Since Python is an evolving language, other sequence data types may be added. There is also another @@ -1879,9 +1879,9 @@ that nested tuples are interpreted correctly; they may be input with or without surrounding parentheses, although often parentheses are necessary anyway (if the tuple is part of a larger expression). -Tuples have many uses, e.g., (x, y) coordinate pairs, employee records -from a database, etc. Tuples, like strings, are immutable: it is not -possible to assign to the individual items of a tuple (you can +Tuples have many uses. For example: (x, y) coordinate pairs, employee +records from a database, etc. Tuples, like strings, are immutable: it +is not possible to assign to the individual items of a tuple (you can simulate much of the same effect with slicing and concatenation, though). It is also possible to create tuples which contain mutable objects, such as lists. @@ -1907,7 +1907,7 @@ Ugly, but effective. For example: The statement \code{t = 12345, 54321, 'hello!'} is an example of \emph{tuple packing}: the values \code{12345}, \code{54321} and \code{'hello!'} are packed together in a tuple. The reverse operation -is also possible, e.g.: +is also possible: \begin{verbatim} >>> x, y, z = t @@ -1992,8 +1992,9 @@ only matters for mutable objects like lists. All comparison operators have the same priority, which is lower than that of all numerical operators. -Comparisons can be chained: e.g., \code{a < b == c} tests whether -\code{a} is less than \code{b} and moreover \code{b} equals \code{c}. +Comparisons can be chained. For example, \code{a < b == c} tests +whether \code{a} is less than \code{b} and moreover \code{b} equals +\code{c}. Comparisons may be combined by the Boolean operators \code{and} and \code{or}, and the outcome of a comparison (or of any other Boolean @@ -2198,7 +2199,7 @@ When a module named \module{spam} is imported, the interpreter searches for a file named \file{spam.py} in the current directory, and then in the list of directories specified by the environment variable \envvar{PYTHONPATH}. This has the same syntax as -the shell variable \envvar{PATH}, i.e., a list of +the shell variable \envvar{PATH}, that is, a list of directory names. When \envvar{PYTHONPATH} is not set, or when the file is not found there, the search continues in an installation-dependent default path; on \UNIX{}, this is usually \file{.:/usr/local/lib/python}. @@ -2289,7 +2290,8 @@ document, the \citetitle[../lib/lib.html]{Python Library Reference} interpreter; these provide access to operations that are not part of the core of the language but are nevertheless built in, either for efficiency or to provide access to operating system primitives such as -system calls. The set of such modules is a configuration option; e.g., +system calls. The set of such modules is a configuration option which +also dependson the underlying platform For example, the \module{amoeba} module is only provided on systems that somehow support Amoeba primitives. One particular module deserves some attention: \module{sys}\refstmodindex{sys}, which is built into every @@ -2316,7 +2318,7 @@ The variable \code{sys.path} is a list of strings that determine the interpreter's search path for modules. It is initialized to a default path taken from the environment variable \envvar{PYTHONPATH}, or from a built-in default if \envvar{PYTHONPATH} is not set. You can modify -it using standard list operations, e.g.: +it using standard list operations: \begin{verbatim} >>> import sys @@ -2384,15 +2386,15 @@ about each other's module names. Suppose you want to design a collection of modules (a ``package'') for the uniform handling of sound files and sound data. There are many different sound file formats (usually recognized by their extension, -e.g. \file{.wav}, \file{.aiff}, \file{.au}), so you may need to create -and maintain a growing collection of modules for the conversion -between the various file formats. There are also many different -operations you might want to perform on sound data (e.g. mixing, -adding echo, applying an equalizer function, creating an artificial -stereo effect), so in addition you will be writing a never-ending -stream of modules to perform these operations. Here's a possible -structure for your package (expressed in terms of a hierarchical -filesystem): +for example: \file{.wav}, \file{.aiff}, \file{.au}), so you may need +to create and maintain a growing collection of modules for the +conversion between the various file formats. There are also many +different operations you might want to perform on sound data (such as +mixing, adding echo, applying an equalizer function, creating an +artificial stereo effect), so in addition you will be writing a +never-ending stream of modules to perform these operations. Here's a +possible structure for your package (expressed in terms of a +hierarchical filesystem): \begin{verbatim} Sound/ Top-level package @@ -2436,7 +2438,7 @@ import Sound.Effects.echo \end{verbatim} This loads the submodule \module{Sound.Effects.echo}. It must be referenced -with its full name, e.g. +with its full name. \begin{verbatim} Sound.Effects.echo.echofilter(input, output, delay=0.7, atten=4) @@ -2523,7 +2525,7 @@ initialization code, \file{__init__.py}) and then imports whatever names are defined in the package. This includes any names defined (and submodules explicitly loaded) by \file{__init__.py}. It also includes any submodules of the package that were explicitly loaded by previous -import statements, e.g. +import statements. Consider this code: \begin{verbatim} import Sound.Effects.echo @@ -2703,8 +2705,8 @@ Using the \code{\%} operator looks like this: The value of PI is approximately 3.142. \end{verbatim} -If there is more than one format in the string you pass a tuple as -right operand, e.g. +If there is more than one format in the string, you need to pass a +tuple as right operand, as in this example: \begin{verbatim} >>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 7678} @@ -2727,7 +2729,7 @@ C formats \code{\%n} and \code{\%p} are not supported. If you have a really long format string that you don't want to split up, it would be nice if you could reference the variables to be formatted by name instead of by position. This can be done by using -an extension of C formats using the form \code{\%(name)format}, e.g. +form \code{\%(name)format}, as shown here: \begin{verbatim} >>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 8637678} @@ -3042,8 +3044,8 @@ A \keyword{try} statement may have more than one except clause, to specify handlers for different exceptions. At most one handler will be executed. Handlers only handle exceptions that occur in the corresponding try clause, not in other handlers of the same -\keyword{try} statement. An except clause may name multiple exceptions -as a parenthesized list, e.g.: +\keyword{try} statement. An except clause may name multiple exceptions +as a parenthesized list, for example: \begin{verbatim} ... except (RuntimeError, TypeError, NameError): @@ -3310,8 +3312,9 @@ global names defined in the module: they share the same namespace! Attributes may be read-only or writable. In the latter case, assignment to attributes is possible. Module attributes are writable: you can write \samp{modname.the_answer = 42}. Writable attributes may -also be deleted with the \keyword{del} statement, e.g. -\samp{del modname.the_answer}. +also be deleted with the \keyword{del} statement. For example, +\samp{del modname.the_answer} will remove the attribute +\member{the_answer} from the object named by \code{modname}. Name spaces are created at different moments and have different lifetimes. The namespace containing the built-in names is created @@ -3338,7 +3341,7 @@ the namespace. Although scopes are determined statically, they are used dynamically. At any time during execution, exactly three nested scopes are in use -(i.e., exactly three namespaces are directly accessible): the +(exactly three namespaces are directly accessible): the innermost scope, which is searched first, contains the local names, the middle scope, searched next, contains the current module's global names, and the outermost scope (searched last) is the namespace @@ -3512,7 +3515,7 @@ del x.counter The second kind of attribute references understood by instance objects are \emph{methods}. A method is a function that ``belongs to'' an object. (In Python, the term method is not unique to class instances: -other object types can have methods as well, e.g., list objects have +other object types can have methods as well. For example, list objects have methods called append, insert, remove, sort, and so on. However, below, we'll use the term method exclusively to mean methods of class instance objects, unless explicitly stated otherwise.) @@ -3529,7 +3532,7 @@ a function object. \subsection{Method Objects \label{methodObjects}} -Usually, a method is called immediately, e.g.: +Usually, a method is called immediately: \begin{verbatim} x.f() @@ -3583,9 +3586,10 @@ list, and the function object is called with this new argument list. Data attributes override method attributes with the same name; to avoid accidental name conflicts, which may cause hard-to-find bugs in large programs, it is wise to use some kind of convention that -minimizes the chance of conflicts, e.g., capitalize method names, -prefix data attribute names with a small unique string (perhaps just -an underscore), or use verbs for methods and nouns for data attributes. +minimizes the chance of conflicts. Possible conventions include +capitalizing method names, prefixing data attribute names with a small +unique string (perhaps just an underscore), or using verbs for methods +and nouns for data attributes. Data attributes may be referenced by methods as well as by ordinary @@ -3647,7 +3651,7 @@ the reader of a program. Methods may call other methods by using method attributes of the -\code{self} argument, e.g.: +\code{self} argument: \begin{verbatim} class Bag: @@ -3690,7 +3694,7 @@ class DerivedClassName(BaseClassName): The name \class{BaseClassName} must be defined in a scope containing the derived class definition. Instead of a base class name, an expression is also allowed. This is useful when the base class is -defined in another module, e.g., +defined in another module, \begin{verbatim} class DerivedClassName(modname.BaseClassName): @@ -3785,10 +3789,10 @@ about instance variables defined by derived classes, or mucking with instance variables by code outside the class. Note that the mangling rules are designed mostly to avoid accidents; it still is possible for a determined soul to access or modify a variable that is considered -private. This can even be useful, e.g. for the debugger, and that's -one reason why this loophole is not closed. (Buglet: derivation of a -class with the same name as the base class makes use of private -variables of the base class possible.) +private. This can even be useful in special circumstances, such as in +the debugger, and that's one reason why this loophole is not closed. +(Buglet: derivation of a class with the same name as the base class +makes use of private variables of the base class possible.) Notice that code passed to \code{exec}, \code{eval()} or \code{evalfile()} does not consider the classname of the invoking @@ -3824,7 +3828,7 @@ class VirtualAttributes: Sometimes it is useful to have a data type similar to the Pascal ``record'' or C ``struct'', bundling together a couple of named data -items. An empty class definition will do nicely, e.g.: +items. An empty class definition will do nicely: \begin{verbatim} class Employee: -- cgit v0.12