[issue16155] Some minor doc fixes in Doc/faq
New submission from Ravi Sinha: - 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 ---------- assignee: docs@python components: Documentation files: doc_faq.patch keywords: patch messages: 172254 nosy: Ravi.Sinha, chris.jerdonek, docs@python, r.david.murray, terry.reedy priority: normal severity: normal status: open title: Some minor doc fixes in Doc/faq type: enhancement versions: Python 3.4 Added file: http://bugs.python.org/file27463/doc_faq.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16155> _______________________________________
Chris Jerdonek added the comment:
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). ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16155> _______________________________________
Terry J. Reedy added the comment: 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. ---------- versions: +Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16155> _______________________________________
Changes by Ezio Melotti <ezio.melotti@gmail.com>: ---------- nosy: +ezio.melotti _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16155> _______________________________________
Ravi Sinha added the comment: 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. ---------- Added file: http://bugs.python.org/file27652/27.doc_faq_Oct21_2012.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16155> _______________________________________
Changes by Ravi Sinha <rss1406@gmail.com>: Added file: http://bugs.python.org/file27653/32.doc_faq_Oct21_2012.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16155> _______________________________________
Changes by Ravi Sinha <rss1406@gmail.com>: Added file: http://bugs.python.org/file27654/33.doc_faq_Oct21_2012.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16155> _______________________________________
Changes by Ravi Sinha <rss1406@gmail.com>: Added file: http://bugs.python.org/file27655/34.doc_faq_Oct21_2012.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16155> _______________________________________
Changes by Andrew Svetlov <andrew.svetlov@gmail.com>: ---------- nosy: +asvetlov _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16155> _______________________________________
Changes by Berker Peksag <berker.peksag@gmail.com>: ---------- nosy: +berker.peksag stage: -> patch review versions: +Python 3.5 -Python 3.2, Python 3.3 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16155> _______________________________________
Roundup Robot added the comment: 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 ---------- nosy: +python-dev resolution: -> fixed stage: patch review -> resolved status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16155> _______________________________________
Roundup Robot added the comment: 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 ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16155> _______________________________________
Georg Brandl added the comment: Thanks! ---------- nosy: +georg.brandl _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16155> _______________________________________
participants (8)
-
Andrew Svetlov -
Berker Peksag
-
Chris Jerdonek
-
Ezio Melotti
-
Georg Brandl
-
Ravi Sinha
-
Roundup Robot
-
Terry J. Reedy