This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: Minor documentation fixes
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.2, Python 3.3, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: ezio.melotti Nosy List: docs@python, eric.araujo, ezio.melotti, georg.brandl, michael.foord, python-dev, r.david.murray, sandro.tosi
Priority: normal Keywords: patch

Created on 2012-05-10 11:01 by michael.foord, last changed 2022-04-11 14:57 by admin. This issue is now closed.

Files
File name Uploaded Description Edit
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.
Messages (8)
msg160333 - (view) Author: Michael Foord (michael.foord) * (Python committer) 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 (&#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()".
msg160343 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) 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) * (Python committer) 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) * (Python committer) Date: 2012-05-10 15:04
Addressed 5) and 8).
msg160391 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) 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) (Python triager) 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) (Python triager) 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) * (Python committer) Date: 2012-05-13 17:23
I addressed Éric comments and committed the patch.
History
Date User Action Args
2022-04-11 14:57:30adminsetgithub: 58975
2012-05-13 17:23:42ezio.melottisetstatus: open -> closed
resolution: fixed
messages: + msg160530

stage: patch review -> resolved
2012-05-13 17:19:49python-devsetmessages: + msg160529
2012-05-13 17:18:17python-devsetnosy: + python-dev
messages: + msg160528
2012-05-11 00:06:31eric.araujosetmessages: + msg160391
2012-05-10 15:04:09ezio.melottisetfiles: + issue14770-2.diff

messages: + msg160349
2012-05-10 14:34:11georg.brandlsetnosy: + georg.brandl
messages: + msg160345
2012-05-10 13:13:14ezio.melottisetfiles: + issue14770.diff

type: enhancement
assignee: docs@python -> ezio.melotti

keywords: + patch
nosy: + ezio.melotti, sandro.tosi, eric.araujo, r.david.murray
messages: + msg160343
stage: needs patch -> patch review
2012-05-10 11:01:23michael.foordcreate