[docs] [issue14770] Minor documentation fixes

[Michael Foord]

New submission from Michael Foord <michael at 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 (&#8221;). It should be an open-quote
symbol (&#8220). 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 at python
components: Documentation
messages: 160333
nosy: docs at 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 <report at bugs.python.org>
<http://bugs.python.org/issue14770>
_______________________________________