Created on 2012-05-10 11:01 by michael.foord, last changed 2012-05-13 17:23 by ezio.melotti. This issue is now closed.
|issue14770.diff||ezio.melotti, 2012-05-10 13:13||Patch against 2.7.|
|issue14770-2.diff||ezio.melotti, 2012-05-10 15:04||Patch against 2.7.|
|msg160333 - (view)||Author: Michael Foord (michael.foord) *||Date: 2012-05-10 11:01|
A bunch of minor fixes for the documentation suggested by Kurt Robinson to the webmaster email address: Below, you will find 15 snippets from the Python 2.7.2 Library and Extension FAQ (http://docs.python.org/faq/library.html), categorized by problem type, accompanied by changes I would suggest or by questions I would have for the author. ********** Wrong word or missing word ********** (1) CURRENT TEXT: "Eventually you'll learn what's in the standard library and will able to skip this step." SUGGESTION: Change "will able" to "will be able". (2) CURRENT TEXT: "The location of the sendmail program varies between systems; sometimes it is /usr/lib/sendmail, sometime /usr/sbin/sendmail." SUGGESTION: Replace "sometime" with "sometimes". (3) CURRENT TEXT: "The Python parent can of course explicitly flush the data it sends to the child before it reads any output, but if the child is a naive C program it may have been written to never explicitly flush its output, even if it is interactive, since flushing is normally automatic." QUESTION: Is "naive C program" the intended wording or should it be "native C program"? (4) CURRENT TEXT: "[HTMLgen is] used when you are writing in Python and wish to synthesize HTML pages for generating a web or for CGI forms, etc." QUESTION: I believe "web" should be "webpage". Correct? (5) CURRENT TEXT: "The default format used by the pickle module is a slow one that results in readable pickles. Making it the default, but it would break backward compatibility." QUESTION: It looks like some words have been left out of the second sentence. What is the intended meaning there? ********** Punctuation issues ********** (6) CURRENT TEXT: "The standard Python source distribution comes with a curses module in the Modules/ subdirectory, though it's not compiled by default (note that this is not available in the Windows distribution - there is no curses module for Windows)." SUGGESTIONS: I believe the major style guides are in agreement that a complete-sentence parenthetical note falling at the end of another sentence should be punctuated as a separate sentence. I also think a semicolon would be more comfortable doing what that dash is doing, but I suppose that's a judgment call. Here's my suggested rewrite for the end of the sentence: ".though it's not compiled by default. (Note that this is not available in the Windows distribution; there is no curses module for Windows)." (7) CURRENT TEXT: "Thus, to read n bytes from a pipe p created with os.popen(), you need to use p.read(n)." SUGGESTION: Put commas before and after "p", or remove the "a" in front of "pipe". (8) CURRENT TEXT: 'For example to send name= "Guy Steele, Jr." .' SUGGESTIONS: Though it won't be apparent in this email, the quotation mark before "Guy" is a close-quote symbol (”). It should be an open-quote symbol (“). I would also put a comma after "for example". (9) CURRENT TEXT: "For example loading a half megabyte of data may take less than a third of a second." SUGGESTION: Insert a comma after "For example". ********** Ambiguity (or at least a momentary miscue) ********** (10) CURRENT TEXT: "For testing, it helps to write the program so that it may be easily tested by using good modular design." SUGGESTION: Though it will be clear for most readers that "by using good modular design" describes the writing process and not the testing process, a rewrite could avoid the miscue and improve the flow: "To get the most out of testing, you should use good modular design in your program." (11) CURRENT TEXT: "A test suite can be associated with each module which automates a sequence of tests." SUGGESTION: Though we can figure out that it's the test suite and not the module which automates a sequence of tests, a rewrite could avoid the miscue and improve readability: "A test suite that automates a sequence of tests can be associated with each module." (12) CURRENT TEXT: "Instead of trying to guess how long a time.sleep() delay will be enough, it's better to use some kind of semaphore mechanism." SUGGESTION: Insert "of" after "how long" to avoid leading to the reader down the path of "how long a time.sleep() delay will last." (13) CURRENT TEXT: "The Queue class maintains a list of objects with .put(obj) to add an item to the queue and .get() to return an item." SUGGESTIONS: Again, we can figure out that those are methods on the class not methods on the objects, but rephrasing the sentence so that it says that unambiguously makes for easier reading: "The Queue class maintains a list of objects and has a .put(obj) method, which adds items to the queue, and .get() method, which returns an item. Shifting momentarily to "content perspective", I think it could be helpful to be more specific about what .get() does. I would suggest changing "returns an item" to something like "returns the item which has been in the queue the longest". ********** Miscellaneous ********** (14) CURRENT TEXT: "This can be caused because the parent expects the child to output more text than it does, or it can be caused by data being stuck in stdio buffers due to lack of flushing." SUGGESTION: "Caused because" strikes my ear as slightly redundant and awkward, but perhaps that's just me. In any case, I think the sentence would read better if it had a more parallel structure: "This can be caused by the parent expecting the child to output more text than it does or by data being stuck in stdio buffers due to lack of flushing." (15) CURRENT TEXT: "The atexit module provides a register function that is similar to C's onexit." SUGGESTION: Change "onexit" to "onexit()".
|msg160343 - (view)||Author: Ezio Melotti (ezio.melotti) *||Date: 2012-05-10 13:13|
Attached a patch that addresses these problems: 1) done; 2) done; 3) I think "naive" is correct here (i.e. a naive program won't take care of flushing); 4) I remove the list of modules and left the link to the wiki page; 5) In the rst source there's a note that says "update this, default protocol is 2/3", but the pickle doc says "If a protocol is not specified, protocol 0 is used.". I left this unchanged for now; 6) done, but the dash seems ok to me, so I left it; 7) the comma sounds wrong to me, but I turned p to italic; 8) I think this is a Sphinx glitch (there might be already an issue for this somewhere). I added the comma; 9) done; 10) I rephrased the sentence; 11) done; 12) I rephrased the sentence; 13) I rephrased the sentence; 14) done; 15) done;
|msg160345 - (view)||Author: Georg Brandl (georg.brandl) *||Date: 2012-05-10 14:34|
Re 5: the sentence needs to be rephrased in any case, because it's ungrammatical Re 8: it's not text, it's code, so it needs to go in code markup
|msg160349 - (view)||Author: Ezio Melotti (ezio.melotti) *||Date: 2012-05-10 15:04|
Addressed 5) and 8).
|msg160391 - (view)||Author: Éric Araujo (eric.araujo) *||Date: 2012-05-11 00:06|
A lot of good editions! +``$PATH``:: Would it be worth using :envvar:`PATH` here? Python-specific envvars (e.g. PYTHONPATH) are documented and can be linked to, maybe a small entry to explain common envvars like HOME and PATH would be a useful addition for novice programmers. +module in the :file:`Modules` subdirectory, You can also use :source:`Modules` to generate a link to the repo; for people who don’t know how to get a Python clone or source distribution (or don’t want to), a link is better than just a file name. +When run, this will produce the following output:: Using “.. code-block:: none” here would avoid misleading colorization. -Thus, to read n bytes from a pipe p created with :func:`os.popen`, you need to +Thus, to read n bytes from a pipe *p* created with :func:`os.popen`, you need to I’d mark up *n* too. +varies between systems; sometimes it is ``/usr/lib/sendmail``, sometimes That’s a program name too, so for consistency you could use :program:, although I’m not sure that role is worth using. +By default :mod:`pickle` uses a relatively old and slow format for backward +compatibility. I trust you will update that comment for the 3.x version.
|msg160528 - (view)||Author: Roundup Robot (python-dev)||Date: 2012-05-13 17:18|
New changeset 9d2a1f35421d by Ezio Melotti in branch '2.7': #14770: improve the library FAQ. http://hg.python.org/cpython/rev/9d2a1f35421d New changeset 7a046f1ddd07 by Ezio Melotti in branch '3.2': #14770: improve the library FAQ. http://hg.python.org/cpython/rev/7a046f1ddd07 New changeset 59fd56c1be0d by Ezio Melotti in branch 'default': #14770: merge with 3.2. http://hg.python.org/cpython/rev/59fd56c1be0d
|msg160529 - (view)||Author: Roundup Robot (python-dev)||Date: 2012-05-13 17:19|
New changeset bf3cb58dcfe7 by Ezio Melotti in branch '2.7': #14770: backport a couple of changes from 3.x. http://hg.python.org/cpython/rev/bf3cb58dcfe7
|msg160530 - (view)||Author: Ezio Melotti (ezio.melotti) *||Date: 2012-05-13 17:23|
I addressed Éric comments and committed the patch.
|2012-05-13 17:23:42||ezio.melotti||set||status: open -> closed|
messages: + msg160530
stage: patch review -> committed/rejected
|2012-05-13 17:19:49||python-dev||set||messages: + msg160529|
messages: + msg160528
|2012-05-11 00:06:31||eric.araujo||set||messages: + msg160391|
messages: + msg160349
messages: + msg160345
assignee: docs@python -> ezio.melotti
keywords: + patch
nosy: + ezio.melotti, sandro.tosi, eric.araujo, r.david.murray
messages: + msg160343
stage: needs patch -> patch review