New submission from Michael Foord <mich...@voidspace.org.uk>: 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()". ---------- assignee: docs@python components: Documentation messages: 160333 nosy: docs@python, michael.foord priority: normal severity: normal stage: needs patch status: open title: Minor documentation fixes versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <rep...@bugs.python.org> <http://bugs.python.org/issue14770> _______________________________________ _______________________________________________ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com