[issue16827] Remove the relatively advanced content from section 2 in tutorial
New submission from Ramchandra Apte: Most of the content in section 2 in the tutorial, http://docs.python.org/3/tutorial/interpreter.html , is relatively advanced and doesn't belong in, at least, the beginning of the tutorial. Only 2.1. Invoking the Interpreter, and 2.2.3. Source Code Encoding should be in section 2. The rest can be moved outside the tutorial, or in later portions. Thanks to Ezio Melotti for helping me overcome my laziness in filing this bug. ---------- assignee: docs@python components: Documentation messages: 178680 nosy: docs@python, ramchandra.apte priority: normal severity: normal status: open title: Remove the relatively advanced content from section 2 in tutorial _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16827> _______________________________________
Ezio Melotti added the comment: +1 ---------- keywords: +easy nosy: +chris.jerdonek, ezio.melotti stage: -> needs patch type: -> enhancement versions: +Python 2.7, Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16827> _______________________________________
Senthil Kumaran added the comment: +1 from me as well. I am also adding Eric who might have views on the customization part which added by him. ---------- nosy: +eric.araujo, orsenthil _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16827> _______________________________________
Ezio Melotti added the comment: Those section could be moved to an appendix or somewhere near http://docs.python.org/3/tutorial/interactive.html. Note that this page and the one about float issues could be appendices too. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16827> _______________________________________
Jamayla Wiley added the comment: I moved the advanced content (all but 2.1, 2.2.3) from the 'Interpreter' tutorial to the 'Interactive' appendix mentioned above. ---------- keywords: +patch nosy: +jdwiley Added file: http://bugs.python.org/file34472/interpreter.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16827> _______________________________________
Ya-Ting Huang added the comment: Hi I just uploaded my patch. I add one file appendix.rst, and move every part except 2.1 and 2.2.3 to appendix. Also I add one line under the interactive section to advice readers see more information in appendix. Please let me know if I should reorganize anything else. By the way the section 13 http://docs.python.org/3/tutorial/interactive.html is more about interactive Input editing, which is different concept from interactive mode. I think it would be good to make clearer of these two. ---------- nosy: +yating.huang Added file: http://bugs.python.org/file34473/tutorial.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16827> _______________________________________
Éric Araujo added the comment: Thanks for the patch, I left a couple notes on the review site (http://bugs.python.org/review/16827/). Ezio suggested moving the doc about floating point issues to an appendix too; what’s your opinion on that? I wonder if the advanced contents should be placed in appendices in the tutorial or merged with the rest of the docs (language or library reference). I guess the idea of tutorial appendices is that people can think they are not required reading and skip them, but know they are here if needed? If that works, I’m all for it. Jamayla, your patch is not in a form that’s easy to review. This page gives help about how to use Merurial to track changes instead of working with copies of files: http://docs.python.org/devguide/patch.html ---------- versions: +Python 3.5 -Python 3.2, Python 3.3 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16827> _______________________________________
Éric Araujo added the comment:
By the way the section 13 is more about interactive Input editing, which is different concept from interactive mode.
I think these are the same thing. Can you explain more? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16827> _______________________________________
Senthil Kumaran added the comment: For this bug, I think, section 2.2.4 and section 2.2.5 can be moved to section 13 and inserted between section 13.1 and 13.2 as it seem to be fit in naturally there. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16827> _______________________________________
James Brewer added the comment: It seems like this issue lost traction, so I decided to go ahead and apply Eric's feedback. I've attached the relevant patch. With that said, I agree with Senthil that sections 2.2.4 and 2.2.5 would be better off between sections 13.1 and 13.2 ---------- nosy: +brwr Added file: http://bugs.python.org/file35015/tutorial-docs-update.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16827> _______________________________________
Changes by Berker Peksag <berker.peksag@gmail.com>: ---------- stage: needs patch -> patch review _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16827> _______________________________________
Changes by Berker Peksag <berker.peksag@gmail.com>: ---------- nosy: +berker.peksag _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16827> _______________________________________
Berker Peksag added the comment: Thanks for the patch, James. Did you see my review comments on Rietveld? Please see at http://bugs.python.org/review/16827/#ps11699 ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16827> _______________________________________
Roundup Robot added the comment: New changeset 2e3a81a0fa14 by Senthil Kumaran in branch '2.7': Issue #16827: Make Interpreter introduction section of the tutorial more https://hg.python.org/cpython/rev/2e3a81a0fa14 New changeset 1e81c7a261a7 by Senthil Kumaran in branch '3.4': Issue #16827: Make Interpreter introduction section of the tutorial more https://hg.python.org/cpython/rev/1e81c7a261a7 New changeset ea401e7c55e4 by Senthil Kumaran in branch 'default': merge from 3.4 https://hg.python.org/cpython/rev/ea401e7c55e4 ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16827> _______________________________________
Senthil Kumaran added the comment: I addressed Berker Peksag's review comments on Jame's patch, tested the local building of docs, verified the content and looks. Committed this in 2.7, 3.4 and 3.5. Thank you all! ---------- assignee: docs@python -> orsenthil resolution: -> fixed stage: patch review -> resolved status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16827> _______________________________________
participants (9)
-
Berker Peksag -
Ezio Melotti
-
Jamayla Wiley
-
James Brewer
-
Ramchandra Apte
-
Roundup Robot
-
Senthil Kumaran
-
Ya-Ting Huang
-
Éric Araujo