[docs] Improve the "introduction" page of the tutorial (issue 14097)

ezio.melotti at gmail.com ezio.melotti at gmail.com
Tue Apr 2 01:19:18 CEST 2013


http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst
File Doc/tutorial/introduction.rst (left):

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#oldcode294
Doc/tutorial/introduction.rst:294: >>> word[:2]    # The first two
characters
Most of these examples have been reorganized to introduce the concept
more gradually.

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#oldcode412
Doc/tutorial/introduction.rst:412: About Unicode
I think this can be postponed until bytes are introduced.  Maybe it
should be mentioned briefly that strings support Unicode though.

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#oldcode551
Doc/tutorial/introduction.rst:551: object!  We'll come back to *object
semantics* later.
This is a fundamental concept, and this lighthearted introduction only
serves to add more confusion IMHO.
I removed the example for now, but this should be covered at a later
point.

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst
File Doc/tutorial/introduction.rst (right):

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode203
Doc/tutorial/introduction.rst:203: 'unununium'
All the changes from this point onward are new in this patch, the
previous patch didn't include any of these.

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode232
Doc/tutorial/introduction.rst:232: 
Double empty line.

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode235
Doc/tutorial/introduction.rst:235: ::
This can be moved at the end of the previous sentence; also the previous
line is too long.

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode280
Doc/tutorial/introduction.rst:280: One way to remember how slices work
is to think of the indices as pointing
While this is useful for slicing, it doesn't work too well for indexing,
where placing the index *below* (rather than *in between*) works better.
Should I show both the examples?

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode286
Doc/tutorial/introduction.rst:286: | H | e | l | p | A |
The sample text should be changed.

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode514
Doc/tutorial/introduction.rst:514: >>> while b < 1000:
This still needs to be changed, but I'm not sure how yet.
I think it would be best to introduce "if" and "for" first, but this is
done in the next page IIRC, so it might be better to move this whole
example in the next page.

http://bugs.python.org/review/14097/


More information about the docs mailing list