classification
Title: Remove the relatively advanced content from section 2 in tutorial
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.4, Python 3.5, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: orsenthil Nosy List: Ramchandra Apte, berker.peksag, brwr, chris.jerdonek, docs@python, eric.araujo, ezio.melotti, jdwiley, orsenthil, python-dev, yating.huang
Priority: normal Keywords: easy, patch

Created on 2012-12-31 14:41 by Ramchandra Apte, last changed 2014-09-18 13:40 by orsenthil. This issue is now closed.

Files
File name Uploaded Description Edit
interpreter.patch jdwiley, 2014-03-18 00:46
tutorial.patch yating.huang, 2014-03-18 01:16 review
tutorial-docs-update.patch brwr, 2014-04-24 03:38 review
Messages (13)
msg178680 - (view) Author: Ramchandra Apte (Ramchandra Apte) * Date: 2012-12-31 14:41
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.
msg178681 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-12-31 14:45
+1
msg178714 - (view) Author: Senthil Kumaran (orsenthil) * (Python committer) Date: 2012-12-31 20:59
+1 from me as well. I am also adding Eric who might have views on the customization part which added by him.
msg178844 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2013-01-02 20:04
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.
msg213924 - (view) Author: Jamayla Wiley (jdwiley) * Date: 2014-03-18 00:46
I moved the advanced content (all but 2.1, 2.2.3) from the 'Interpreter' tutorial to the 'Interactive' appendix mentioned above.
msg213928 - (view) Author: Ya-Ting Huang (yating.huang) * Date: 2014-03-18 01:16
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.
msg214059 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2014-03-19 06:44
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
msg214062 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2014-03-19 07:02
> 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?
msg216863 - (view) Author: Senthil Kumaran (orsenthil) * (Python committer) Date: 2014-04-19 15:55
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.
msg217113 - (view) Author: James Brewer (brwr) Date: 2014-04-24 03:38
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
msg227027 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2014-09-18 03:17
Thanks for the patch, James. Did you see my review comments on Rietveld? Please see at http://bugs.python.org/review/16827/#ps11699
msg227042 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2014-09-18 13:38
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
msg227043 - (view) Author: Senthil Kumaran (orsenthil) * (Python committer) Date: 2014-09-18 13:40
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!
History
Date User Action Args
2014-09-18 13:40:24orsenthilsetstatus: open -> closed
messages: + msg227043

assignee: docs@python -> orsenthil
resolution: fixed
stage: patch review -> resolved
2014-09-18 13:38:10python-devsetnosy: + python-dev
messages: + msg227042
2014-09-18 03:17:50berker.peksagsetmessages: + msg227027
2014-09-18 03:10:48berker.peksagsetnosy: + berker.peksag
2014-09-18 03:09:47berker.peksagsetstage: needs patch -> patch review
2014-04-24 03:38:55brwrsetfiles: + tutorial-docs-update.patch
nosy: + brwr
messages: + msg217113

2014-04-19 15:55:30orsenthilsetmessages: + msg216863
2014-03-19 07:02:49eric.araujosetmessages: + msg214062
2014-03-19 06:44:49eric.araujosetmessages: + msg214059
versions: + Python 3.5, - Python 3.2, Python 3.3
2014-03-18 01:16:17yating.huangsetfiles: + tutorial.patch
nosy: + yating.huang
messages: + msg213928

2014-03-18 00:46:10jdwileysetfiles: + interpreter.patch

nosy: + jdwiley
messages: + msg213924

keywords: + patch
2013-01-02 20:04:17ezio.melottisetmessages: + msg178844
2012-12-31 20:59:05orsenthilsetnosy: + eric.araujo, orsenthil
messages: + msg178714
2012-12-31 14:45:51ezio.melottisettype: enhancement
versions: + Python 2.7, Python 3.2, Python 3.3, Python 3.4
keywords: + easy
nosy: + chris.jerdonek, ezio.melotti

messages: + msg178681
stage: needs patch
2012-12-31 14:41:36Ramchandra Aptecreate