classification
Title: Some minor doc fixes in Doc/faq
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.5, Python 3.4, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Ravi.Sinha, asvetlov, berker.peksag, chris.jerdonek, docs@python, ezio.melotti, georg.brandl, python-dev, r.david.murray, terry.reedy
Priority: normal Keywords: patch

Created on 2012-10-06 22:29 by Ravi.Sinha, last changed 2014-10-06 15:52 by georg.brandl. This issue is now closed.

Files
File name Uploaded Description Edit
doc_faq.patch Ravi.Sinha, 2012-10-06 22:29 Minor doc fixes in Doc/faq for doctest review
27.doc_faq_Oct21_2012.patch Ravi.Sinha, 2012-10-21 19:57 Patch for 2.7 review
32.doc_faq_Oct21_2012.patch Ravi.Sinha, 2012-10-21 19:57 Patch for 3.2 review
33.doc_faq_Oct21_2012.patch Ravi.Sinha, 2012-10-21 19:58 Patch for 3.3 review
34.doc_faq_Oct21_2012.patch Ravi.Sinha, 2012-10-21 19:58 Patch for 3.4 review
Messages (7)
msg172254 - (view) Author: Ravi Sinha (Ravi.Sinha) Date: 2012-10-06 22:29
- help(fn) which in the REPL leads to a new pager/ display - seems to be difficult to test with doctest - it does not seem to pick the whitespace in the docs and does not match - Doc/faq/general.rst
        - os.path.isdir returns True or False, not 0 or 1 as in the docs, but I didn't know if I should change that - Doc/faq/windows.rst
msg172295 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-10-07 12:35
> it does not seem to pick the whitespace in the docs and does not match - Doc/faq/general.rst

Can you provide a link to the line (or one of the lines) in question so it's easier to see what you are referring to?

> os.path.isdir returns True or False, not 0 or 1 as in the docs

I think there is a doctest directive to make 1 acceptable for True and vice versa, but it's generally better if the docs match what Python actually returns (for that version of Python).
msg172326 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2012-10-07 17:56
Doc corrections (can) go in all current docs.

1.2 - 1.0: same change
"Hello" * 3: same change

dir([]): shouldn't output be line-wrapped
3.3: same
3.2: delete __dir__, clear, copy, giving
['__add__', '__class__', '__contains__', '__delattr__', '__delitem__', '__doc__', '__eq__', '__format__', '__ge__', '__getattribute__', '__getitem__', '__gt__', '__hash__', '__iadd__', '__imul__', '__init__', '__iter__', '__le__', '__len__', '__lt__', '__mul__', '__ne__', '__new__', '__reduce__', '__reduce_ex__', '__repr__', '__reversed__', '__rmul__', '__setattr__', '__setitem__', '__sizeof__', '__str__', '__subclasshook__', 'append', 'count', 'extend', 'index', 'insert', 'pop', 'remove', 'reverse', 'sort']

2.7: same deletions, add __delslice__, __getslice__, __setslice__, giving
['__add__', '__class__', '__contains__', '__delattr__', '__delitem__', '__dir__', '__doc__', '__eq__', '__format__', '__ge__', '__getattribute__', '__getitem__', '__gt__', '__hash__', '__iadd__', '__imul__', '__init__', '__iter__', '__le__', '__len__', '__lt__', '__mul__', '__ne__', '__new__', '__reduce__', '__reduce_ex__', '__repr__', '__reversed__', '__rmul__', '__setattr__', '__setitem__', '__sizeof__', '__str__', '__subclasshook__', 'append', 'clear', 'copy', 'count', 'extend', 'index', 'insert', 'pop', 'remove', 'reverse', 'sort']

# for 2.7, 3.2, delete clear, copy for
>>> [d for d in dir([]) if '__' not in d]
['append', 'count', 'extend', 'index', 'insert', 'pop', 'remove', 'reverse', 'sort']

Change Boolean 0,1 outputs to False,True. This was done in most places when behavior was changed after booleans were added in 2.2, or you would see many more errors. This holdover in the faq is an oversight.

In 3.3 and before, help() does not lead to a new pager/display on Windows, so I am not sure what you mean. I presume you are referring to the following.

>>> help(L.append)
Help on built-in function append:

append(...)
    L.append(object) -> None -- append object to end

>>> 

The above from 3.3, and same before, has a blank line that is not in the faq, so add it. It otherwise looks the same to me.
msg173475 - (view) Author: Ravi Sinha (Ravi.Sinha) Date: 2012-10-21 19:57
Did the same changes for versions 2.7, 3.2, 3.3, and 3.4

For line wrap in cases like http://hg.python.org/cpython/file/40a1652349e9/Doc/faq/general.rst, line 448, broke the list across separate lines, and had to use +NORMALIZE_WHITESPACE to make the tests pass.

For the same file, in line 454, versions 2.7 and 3.2 don't have '-> None' while versions 3.3 and 3.4 do. So made the changes accordingly. Adding '<BLANKLINE>' around the contents of the help is making the tests pass too. I am assuming that <BLANKLINE> means the new pager that I get on OS X. This was the case uniformly across all 4 versions.

Attaching all 4 patches, for different versions. Please let me know where to go from here.
msg228709 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2014-10-06 15:51
New changeset 09782fad1825 by Georg Brandl in branch '2.7':
Closes #16155: fix a few errors in doctest output of the FAQ pages.
https://hg.python.org/cpython/rev/09782fad1825
msg228710 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2014-10-06 15:52
New changeset 96eab476d45e by Georg Brandl in branch '3.4':
Closes #16155: fix a few errors in doctest output of the FAQ pages.
https://hg.python.org/cpython/rev/96eab476d45e
msg228711 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2014-10-06 15:52
Thanks!
History
Date User Action Args
2014-10-06 15:52:18georg.brandlsetnosy: + georg.brandl
messages: + msg228711
2014-10-06 15:52:06python-devsetmessages: + msg228710
2014-10-06 15:51:56python-devsetstatus: open -> closed

nosy: + python-dev
messages: + msg228709

resolution: fixed
stage: patch review -> resolved
2014-09-30 23:34:10berker.peksagsetnosy: + berker.peksag
stage: patch review

versions: + Python 3.5, - Python 3.2, Python 3.3
2012-10-25 19:10:34asvetlovsetnosy: + asvetlov
2012-10-21 19:58:39Ravi.Sinhasetfiles: + 34.doc_faq_Oct21_2012.patch
2012-10-21 19:58:17Ravi.Sinhasetfiles: + 33.doc_faq_Oct21_2012.patch
2012-10-21 19:57:59Ravi.Sinhasetfiles: + 32.doc_faq_Oct21_2012.patch
2012-10-21 19:57:36Ravi.Sinhasetfiles: + 27.doc_faq_Oct21_2012.patch

messages: + msg173475
2012-10-08 05:25:45ezio.melottisetnosy: + ezio.melotti
2012-10-07 17:56:36terry.reedysetmessages: + msg172326
versions: + Python 2.7, Python 3.2, Python 3.3
2012-10-07 12:35:05chris.jerdoneksetmessages: + msg172295
2012-10-06 22:29:11Ravi.Sinhacreate