traverseda
/
cpython
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

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.
This commit is contained in:
Fred Drake 2001-07-06 19:28:48 +00:00
parent 6ee4234802
commit 91f2f26d75
12 changed files with 105 additions and 103 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
Doc/lib/libaifc.tex
View File

@ -29,7 +29,7 @@ second's worth of audio consists of
For example, CD quality audio has a sample size of two bytes (16
bits), uses two channels (stereo) and has a frame rate of 44,100
frames/second. This gives a frame size of 4 bytes (2*2), and a
second's worth occupies 2*2*44100 bytes, i.e.\ 176,400 bytes.
second's worth occupies 2*2*44100 bytes (176,400 bytes).
Module \module{aifc} defines the following function:

2
Doc/lib/libarray.tex
View File

@ -108,7 +108,7 @@ except that if there is a type error, the array is unchanged.
\begin{methoddesc}[array]{fromstring}{s}
Appends items from the string, interpreting the string as an
array of machine values (i.e. as if it had been read from a
array of machine values (as if it had been read from a
file using the \method{fromfile()} method).
\end{methoddesc}

2
Doc/lib/libbisect.tex
View File

@ -15,7 +15,7 @@ of items with expensive comparison operations, this can be an
improvement over the more common approach. The module is called
\module{bisect} because it uses a basic bisection algorithm to do its
work. The source code may be most useful as a working example of the
algorithm (i.e., the boundary conditions are already right!).
algorithm (the boundary conditions are already right!).
The following functions are provided:

36
Doc/lib/libcgi.tex
View File

@ -112,7 +112,7 @@ name, the object retrieved by \samp{form[\var{key}]} is not a
instance but a list of such instances. Similarly, in this situation,
\samp{form.getvalue(\var{key})} would return a list of strings.
If you expect this possibility
(i.e., when your HTML form contains multiple fields with the same
(when your HTML form contains multiple fields with the same
name), use the \function{type()} function to determine whether you
have a single instance or a list of instances. For example, here's
code that concatenates any number of username fields, separated by
@ -283,21 +283,21 @@ Convert the characters
HTML-safe sequences. Use this if you need to display text that might
contain such characters in HTML. If the optional flag \var{quote} is
true, the double quote character (\character{"}) is also translated;
this helps for inclusion in an HTML attribute value, e.g. in \code{<A
this helps for inclusion in an HTML attribute value, as in \code{<A
HREF="...">}.
\end{funcdesc}
\subsection{Caring about security}
There's one important rule: if you invoke an external program (e.g.
via the \function{os.system()} or \function{os.popen()} functions),
make very sure you don't pass arbitrary strings received from the
client to the shell. This is a well-known security hole whereby
clever hackers anywhere on the web can exploit a gullible CGI script
to invoke arbitrary shell commands. Even parts of the URL or field
names cannot be trusted, since the request doesn't have to come from
your form!
There's one important rule: if you invoke an external program (via the
\function{os.system()} or \function{os.popen()} functions. or others
with similar functionality), make very sure you don't pass arbitrary
strings received from the client to the shell. This is a well-known
security hole whereby clever hackers anywhere on the web can exploit a
gullible CGI script to invoke arbitrary shell commands. Even parts of
the URL or field names cannot be trusted, since the request doesn't
have to come from your form!
To be on the safe side, if you must pass a string gotten from a form
to a shell command, you should make sure the string contains only
@ -337,7 +337,7 @@ anything interesting.
If you need to load modules from a directory which is not on Python's
default module search path, you can change the path in your script,
before importing other modules, e.g.:
before importing other modules. For example:
\begin{verbatim}
import sys
@ -383,7 +383,7 @@ http://yourhostname/cgi-bin/cgi.py?name=Joe+Blow&addr=At+Home
If this gives an error of type 404, the server cannot find the script
-- perhaps you need to install it in a different directory. If it
gives another error (e.g. 500), there's an installation problem that
gives another error, there's an installation problem that
you should fix before trying to go any further. If you get a nicely
formatted listing of the environment and form content (in this
example, the fields should be listed as ``addr'' with value ``At Home''
@ -402,12 +402,12 @@ cgi.test()
This should produce the same results as those gotten from installing
the \file{cgi.py} file itself.
When an ordinary Python script raises an unhandled exception
(e.g. because of a typo in a module name, a file that can't be opened,
etc.), the Python interpreter prints a nice traceback and exits.
While the Python interpreter will still do this when your CGI script
raises an exception, most likely the traceback will end up in one of
the HTTP server's log file, or be discarded altogether.
When an ordinary Python script raises an unhandled exception (for
whatever reason: of a typo in a module name, a file that can't be
opened, etc.), the Python interpreter prints a nice traceback and
exits. While the Python interpreter will still do this when your CGI
script raises an exception, most likely the traceback will end up in
one of the HTTP server's log file, or be discarded altogether.
Fortunately, once you have managed to get your script to execute
\emph{some} code, it is easy to catch exceptions and cause a traceback

4
Doc/lib/libcurses.tex
View File

@ -331,7 +331,7 @@ A pad is like a window, except that it is not restricted by the screen
size, and is not necessarily associated with a particular part of the
screen. Pads can be used when a large window is needed, and only a
part of the window will be on the screen at one time. Automatic
refreshes of pads (e.g., from scrolling or echoing of input) do not
refreshes of pads (such as from scrolling or echoing of input) do not
occur. The \method{refresh()} and \method{noutrefresh()} methods of a
pad require 6 arguments to specify the part of the pad to be
displayed and the location on the screen to be used for the display.
@ -542,7 +542,7 @@ Window objects, as returned by \function{initscr()} and
following methods:
\begin{methoddesc}{addch}{\optional{y, x,} ch\optional{, attr}}
\strong{Note:} A \emph{character} means a C character (i.e., an
\strong{Note:} A \emph{character} means a C character (an
\ASCII{} code), rather then a Python character (a string of length 1).
(This note is true whenever the documentation mentions a character.)
The builtin \function{ord()} is handy for conveying strings to codes.

8
Doc/lib/libftplib.tex
View File

@ -148,7 +148,7 @@ Raise an exception otherwise.
\begin{methoddesc}{retrbinary}{command,
callback\optional{, maxblocksize\optional{, rest}}}
Retrieve a file in binary transfer mode. \var{command} should be an
appropriate \samp{RETR} command, i.e.\ \code{'RETR \var{filename}'}.
appropriate \samp{RETR} command: \code{'RETR \var{filename}'}.
The \var{callback} function is called for each block of data received,
with a single string argument giving the data block.
The optional \var{maxblocksize} argument specifies the maximum chunk size to
@ -175,7 +175,7 @@ default; in Python 2.1 and later, it is on by default.)
\begin{methoddesc}{storbinary}{command, file\optional{, blocksize}}
Store a file in binary transfer mode. \var{command} should be an
appropriate \samp{STOR} command, i.e.\ \code{"STOR \var{filename}"}.
appropriate \samp{STOR} command: \code{"STOR \var{filename}"}.
\var{file} is an open file object which is read until \EOF{} using its
\method{read()} method in blocks of size \var{blocksize} to provide the
data to be stored. The \var{blocksize} argument defaults to 8192.
@ -281,9 +281,9 @@ calls (see below).
\begin{methoddesc}{close}{}
Close the connection unilaterally. This should not be applied to an
already closed connection (e.g.\ after a successful call to
already closed connection (such as after a successful call to
\method{quit()}. After this call the \class{FTP} instance should not
be used any more (i.e., after a call to \method{close()} or
be used any more (after a call to \method{close()} or
\method{quit()} you cannot reopen the connection by issuing another
\method{login()} method).
\end{methoddesc}

112
Doc/lib/libfuncs.tex
View File

@ -99,10 +99,10 @@ class instances are callable if they have a \method{__call__()} method.
\begin{funcdesc}{chr}{i}
Return a string of one character whose \ASCII{} code is the integer
\var{i}, e.g., \code{chr(97)} returns the string \code{'a'}. This is the
inverse of \function{ord()}. The argument must be in the range [0..255],
inclusive; \exception{ValueError} will be raised if \var{i} is
outside that range.
\var{i}. For example, \code{chr(97)} returns the string \code{'a'}.
This is the inverse of \function{ord()}. The argument must be in
the range [0..255], inclusive; \exception{ValueError} will be raised
if \var{i} is outside that range.
\end{funcdesc}
\begin{funcdesc}{cmp}{x, y}
@ -122,14 +122,14 @@ class instances are callable if they have a \method{__call__()} method.
Compile the \var{string} into a code object. Code objects can be
executed by an \keyword{exec} statement or evaluated by a call to
\function{eval()}. The \var{filename} argument should
give the file from which the code was read; pass e.g. \code{'<string>'}
if it wasn't read from a file. The \var{kind} argument specifies
what kind of code must be compiled; it can be \code{'exec'} if
\var{string} consists of a sequence of statements, \code{'eval'}
if it consists of a single expression, or \code{'single'} if
it consists of a single interactive statement (in the latter case,
expression statements that evaluate to something else than
\code{None} will printed).
give the file from which the code was read; pass same recognizable value
if it wasn't read from a file (\code{'<string>'} is commonly used).
The \var{kind} argument specifies what kind of code must be
compiled; it can be \code{'exec'} if \var{string} consists of a
sequence of statements, \code{'eval'} if it consists of a single
expression, or \code{'single'} if it consists of a single
interactive statement (in the latter case, expression statements
that evaluate to something else than \code{None} will printed).
\end{funcdesc}
\begin{funcdesc}{complex}{real\optional{, imag}}
@ -156,9 +156,9 @@ class instances are callable if they have a \method{__call__()} method.
symbol table. With an argument, attempts to return a list of valid
attribute for that object. This information is gleaned from the
object's \member{__dict__}, \member{__methods__} and \member{__members__}
attributes, if defined. The list is not necessarily complete; e.g.,
for classes, attributes defined in base classes are not included,
and for class instances, methods are not included.
attributes, if defined. The list is not necessarily complete. For
example, for classes, attributes defined in base classes are not
included, and for class instances, methods are not included.
The resulting list is sorted alphabetically. For example:
\begin{verbatim}
@ -202,9 +202,9 @@ class instances are callable if they have a \method{__call__()} method.
\end{verbatim}
This function can also be used to execute arbitrary code objects
(e.g.\ created by \function{compile()}). In this case pass a code
object instead of a string. The code object must have been compiled
passing \code{'eval'} to the \var{kind} argument.
(such as those created by \function{compile()}). In this case pass
a code object instead of a string. The code object must have been
compiled passing \code{'eval'} as the \var{kind} argument.
Hints: dynamic execution of statements is supported by the
\keyword{exec} statement. Execution of statements from a file is
@ -239,7 +239,7 @@ class instances are callable if they have a \method{__call__()} method.
container which supports iteration, or an iterator, If \var{list}
is a string or a tuple, the result also has that type; otherwise it
is always a list. If \var{function} is \code{None}, the identity
function is assumed, i.e.\ all elements of \var{list} that are false
function is assumed, that is, all elements of \var{list} that are false
(zero or empty) are removed.
\end{funcdesc}
@ -286,18 +286,18 @@ module from which it is called).
Return the hash value of the object (if it has one). Hash values
are integers. They are used to quickly compare dictionary
keys during a dictionary lookup. Numeric values that compare equal
have the same hash value (even if they are of different types, e.g.
1 and 1.0).
have the same hash value (even if they are of different types, as is
the case for 1 and 1.0).
\end{funcdesc}
\begin{funcdesc}{hex}{x}
Convert an integer number (of any size) to a hexadecimal string.
The result is a valid Python expression. Note: this always yields
an unsigned literal, e.g. on a 32-bit machine, \code{hex(-1)} yields
\code{'0xffffffff'}. When evaluated on a machine with the same
word size, this literal is evaluated as -1; at a different word
size, it may turn up as a large positive number or raise an
\exception{OverflowError} exception.
an unsigned literal. For example, on a 32-bit machine,
\code{hex(-1)} yields \code{'0xffffffff'}. When evaluated on a
machine with the same word size, this literal is evaluated as -1; at
a different word size, it may turn up as a large positive number or
raise an \exception{OverflowError} exception.
\end{funcdesc}
\begin{funcdesc}{id}{object}
@ -352,7 +352,7 @@ module from which it is called).
be done by a pointer compare instead of a string compare. Normally,
the names used in Python programs are automatically interned, and
the dictionaries used to hold module, class or instance attributes
have interned keys. Interned strings are immortal (i.e. never get
have interned keys. Interned strings are immortal (never get
garbage collected).
\end{funcdesc}
@ -410,36 +410,36 @@ the interpreter.
\end{funcdesc}
\begin{funcdesc}{map}{function, list, ...}
Apply \var{function} to every item of \var{list} and return a list
of the results. If additional \var{list} arguments are passed,
\var{function} must take that many arguments and is applied to
the items of all lists in parallel; if a list is shorter than another
it is assumed to be extended with \code{None} items. If
\var{function} is \code{None}, the identity function is assumed; if
there are multiple list arguments, \function{map()} returns a list
consisting of tuples containing the corresponding items from all lists
(i.e. a kind of transpose operation). The \var{list} arguments may be
any kind of sequence; the result is always a list.
Apply \var{function} to every item of \var{list} and return a list
of the results. If additional \var{list} arguments are passed,
\var{function} must take that many arguments and is applied to the
items of all lists in parallel; if a list is shorter than another it
is assumed to be extended with \code{None} items. If \var{function}
is \code{None}, the identity function is assumed; if there are
multiple list arguments, \function{map()} returns a list consisting
of tuples containing the corresponding items from all lists (a kind
of transpose operation). The \var{list} arguments may be any kind
of sequence; the result is always a list.
\end{funcdesc}
\begin{funcdesc}{max}{s\optional{, args...}}
With a single argument \var{s}, return the largest item of a
non-empty sequence (e.g., a string, tuple or list). With more than
one argument, return the largest of the arguments.
With a single argument \var{s}, return the largest item of a
non-empty sequence (such as a string, tuple or list). With more
than one argument, return the largest of the arguments.
\end{funcdesc}
\begin{funcdesc}{min}{s\optional{, args...}}
With a single argument \var{s}, return the smallest item of a
non-empty sequence (e.g., a string, tuple or list). With more than
one argument, return the smallest of the arguments.
With a single argument \var{s}, return the smallest item of a
non-empty sequence (such as a string, tuple or list). With more
than one argument, return the smallest of the arguments.
\end{funcdesc}
\begin{funcdesc}{oct}{x}
Convert an integer number (of any size) to an octal string. The
result is a valid Python expression. Note: this always yields
an unsigned literal, e.g. on a 32-bit machine, \code{oct(-1)} yields
\code{'037777777777'}. When evaluated on a machine with the same
word size, this literal is evaluated as -1; at a different word
result is a valid Python expression. Note: this always yields an
unsigned literal. For example, on a 32-bit machine, \code{oct(-1)}
yields \code{'037777777777'}. When evaluated on a machine with the
same word size, this literal is evaluated as -1; at a different word
size, it may turn up as a large positive number or raise an
\exception{OverflowError} exception.
\end{funcdesc}
@ -499,8 +499,8 @@ one argument, return the smallest of the arguments.
numeric types. With mixed operand types, the rules for binary
arithmetic operators apply. The effective operand type is also the
type of the result; if the result is not expressible in this type, the
function raises an exception; e.g., \code{pow(2, -1)} or \code{pow(2,
35000)} is not allowed.
function raises an exception; for example, \code{pow(2, -1)} or
\code{pow(2, 35000)} is not allowed.
\end{funcdesc}
\begin{funcdesc}{range}{\optional{start,} stop\optional{, step}}
@ -570,7 +570,7 @@ argument must be a module object, so it must have been successfully
imported before. This is useful if you have edited the module source
file using an external editor and want to try out the new version
without leaving the Python interpreter. The return value is the
module object (i.e.\ the same as the \var{module} argument).
module object (the same as the \var{module} argument).
There are a number of caveats:
@ -623,7 +623,7 @@ when passed to \function{eval()}.
after the decimal point. If \var{n} is omitted, it defaults to zero.
The result is a floating point number. Values are rounded to the
closest multiple of 10 to the power minus \var{n}; if two multiples
are equally close, rounding is done away from 0 (so e.g.
are equally close, rounding is done away from 0 (so. for example,
\code{round(0.5)} is \code{1.0} and \code{round(-0.5)} is \code{-1.0}).
\end{funcdesc}
@ -645,7 +645,7 @@ which merely return the argument values (or their default). They have
no other explicit functionality; however they are used by Numerical
Python\index{Numerical Python} and other third party extensions.
Slice objects are also generated when extended indexing syntax is
used, e.g. for \samp{a[start:stop:step]} or \samp{a[start:stop, i]}.
used. For example: \samp{a[start:stop:step]} or \samp{a[start:stop, i]}.
\end{funcdesc}
\begin{funcdesc}{str}{object}
@ -680,7 +680,7 @@ For instance:
\begin{funcdesc}{unichr}{i}
Return the Unicode string of one character whose Unicode code is the
integer \var{i}, e.g., \code{unichr(97)} returns the string
integer \var{i}. For example, \code{unichr(97)} returns the string
\code{u'a'}. This is the inverse of \function{ord()} for Unicode
strings. The argument must be in the range [0..65535], inclusive.
\exception{ValueError} is raised otherwise.
@ -712,7 +712,7 @@ The returned dictionary should not be modified: the effects on the
corresponding symbol table are undefined.\footnote{
In the current implementation, local variable bindings cannot
normally be affected this way, but variables retrieved from
other scopes (e.g. modules) can be. This may change.}
other scopes (such as modules) can be. This may change.}
\end{funcdesc}
\begin{funcdesc}{xrange}{\optional{start,} stop\optional{, step}}
@ -723,8 +723,8 @@ actually storing them all simultaneously. The advantage of
\function{xrange()} over \function{range()} is minimal (since
\function{xrange()} still has to create the values when asked for
them) except when a very large range is used on a memory-starved
machine (e.g. MS-DOS) or when all of the range's elements are never
used (e.g. when the loop is usually terminated with \keyword{break}).
machine or when all of the range's elements are never used (such as
when the loop is usually terminated with \keyword{break}).
\end{funcdesc}
\begin{funcdesc}{zip}{seq1, \moreargs}

22
Doc/lib/libgettext.tex
View File

@ -41,12 +41,12 @@ where \var{languages} is searched for in the environment variables
If \var{localedir} is omitted or \code{None}, then the current binding
for \var{domain} is returned.\footnote{
The default locale directory is system dependent; e.g.\ on
RedHat Linux it is \file{/usr/share/locale}, but on Solaris it
is \file{/usr/lib/locale}. The \module{gettext} module does
not try to support these system dependent defaults; instead
its default is \file{\code{sys.prefix}/share/locale}. For
this reason, it is always best to call
The default locale directory is system dependent; for example,
on RedHat Linux it is \file{/usr/share/locale}, but on Solaris
it is \file{/usr/lib/locale}. The \module{gettext} module
does not try to support these system dependent defaults;
instead its default is \file{\code{sys.prefix}/share/locale}.
For this reason, it is always best to call
\function{bindtextdomain()} with an explicit absolute path at
the start of your application.}
\end{funcdesc}
@ -141,8 +141,8 @@ function \function{translation()}. The \var{unicode} flag is passed to
the resulting translation object's \method{install} method.
As seen below, you usually mark the strings in your application that are
candidates for translation, by wrapping them in a call to the function
\function{_()}, e.g.
candidates for translation, by wrapping them in a call to the
\function{_()} function, like this:
\begin{verbatim}
print _('This string will be translated.')
@ -287,8 +287,8 @@ steps:
In order to prepare your code for I18N, you need to look at all the
strings in your files. Any string that needs to be translated
should be marked by wrapping it in \code{_('...')} -- i.e. a call to
the function \function{_()}. For example:
should be marked by wrapping it in \code{_('...')} --- that is, a call
to the function \function{_()}. For example:
\begin{verbatim}
filename = 'mylog.txt'
@ -317,7 +317,7 @@ previously marked as translatable. It is similar to the GNU
\program{gettext} program except that it understands all the
intricacies of Python source code, but knows nothing about C or C++
source code. You don't need GNU \code{gettext} unless you're also
going to be translating C code (e.g. C extension modules).
going to be translating C code (such as C extension modules).
\program{pygettext} generates textual Uniforum-style human readable
message catalog \file{.pot} files, essentially structured human

4
Doc/lib/libimp.tex
View File

@ -57,7 +57,7 @@ search is unsuccessful, \exception{ImportError} is raised. Other
exceptions indicate problems with the arguments or environment.
This function does not handle hierarchical module names (names
containing dots). In order to find \var{P}.\var{M}, i.e., submodule
containing dots). In order to find \var{P}.\var{M}, that is, submodule
\var{M} of package \var{P}, use \function{find_module()} and
\function{load_module()} to find and load package \var{P}, and then use
\function{find_module()} with the \var{path} argument set to
@ -211,7 +211,7 @@ source file.
\label{examples-imp}
The following function emulates what was the standard import statement
up to Python 1.4 (i.e., no hierarchical module names). (This
up to Python 1.4 (no hierarchical module names). (This
\emph{implementation} wouldn't work in that version, since
\function{find_module()} has been extended and
\function{load_module()} has been added in 1.4.)

2
Doc/lib/libmd5.tex
View File

@ -50,7 +50,7 @@ An md5 object has the following methods:
\begin{methoddesc}[md5]{update}{arg}
Update the md5 object with the string \var{arg}. Repeated calls are
equivalent to a single call with the concatenation of all the
arguments, i.e.\ \code{m.update(a); m.update(b)} is equivalent to
arguments: \code{m.update(a); m.update(b)} is equivalent to
\code{m.update(a+b)}.
\end{methoddesc}

2
Doc/lib/libmimify.tex
View File

@ -56,7 +56,7 @@ Return a MIME-encoded version of the header line in \var{line}.
\begin{datadesc}{MAXLEN}
By default, a part will be encoded as quoted-printable when it
contains any non-\ASCII{} characters (i.e., characters with the 8th bit
contains any non-\ASCII{} characters (characters with the 8th bit
set), or if there are any lines longer than \constant{MAXLEN} characters
(default value 200).
\end{datadesc}

12
Doc/lib/libnis.tex
View File

@ -5,13 +5,13 @@
\platform{UNIX}
\moduleauthor{Fred Gansevles}{Fred.Gansevles@cs.utwente.nl}
\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
\modulesynopsis{Interface to Sun's NIS (a.k.a. Yellow Pages) library.}
\modulesynopsis{Interface to Sun's NIS (Yellow Pages) library.}
The \module{nis} module gives a thin wrapper around the NIS library, useful
for central administration of several hosts.
Because NIS exists only on \UNIX{} systems, this module is
only available for \UNIX{}.
only available for \UNIX.
The \module{nis} module defines the following functions:
@ -19,10 +19,11 @@ The \module{nis} module defines the following functions:
Return the match for \var{key} in map \var{mapname}, or raise an
error (\exception{nis.error}) if there is none.
Both should be strings, \var{key} is 8-bit clean.
Return value is an arbitrary array of bytes (i.e., may contain \code{NULL}
Return value is an arbitrary array of bytes (may contain \code{NULL}
and other joys).
Note that \var{mapname} is first checked if it is an alias to another name.
Note that \var{mapname} is first checked if it is an alias to another
name.
\end{funcdesc}
\begin{funcdesc}{cat}{mapname}
@ -31,7 +32,8 @@ Return a dictionary mapping \var{key} to \var{value} such that
Note that both keys and values of the dictionary are arbitrary
arrays of bytes.
Note that \var{mapname} is first checked if it is an alias to another name.
Note that \var{mapname} is first checked if it is an alias to another
name.
\end{funcdesc}
\begin{funcdesc}{maps}{}