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

ezio.melotti at gmail.com ezio.melotti at gmail.com
Mon Nov 26 17:32:40 CET 2012


Reviewers: ,


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

http://bugs.python.org/review/14097/diff/6689/Doc/tutorial/introduction.rst#oldcode54
Doc/tutorial/introduction.rst:54: >>> 2+2  # and a comment on the same
line as code
Removed redundant comment examples and cleaned up whitespace.

http://bugs.python.org/review/14097/diff/6689/Doc/tutorial/introduction.rst#oldcode65
Doc/tutorial/introduction.rst:65: representations.
Removed outdated note.

http://bugs.python.org/review/14097/diff/6689/Doc/tutorial/introduction.rst#oldcode92
Doc/tutorial/introduction.rst:92: 0
This can be done and works with immutable values, but might have
surprising side effects with mutable values and about the evaluation
order (see recent python-dev thread).
I think it's better to remove this altogether, since it's rarely needed
anyway.

http://bugs.python.org/review/14097/diff/6689/Doc/tutorial/introduction.rst#oldcode151
Doc/tutorial/introduction.rst:151: 5.0
All this might be moved somewhere else.
For now I just added a mention about complex number at the end of the
section.

http://bugs.python.org/review/14097/diff/6689/Doc/tutorial/introduction.rst#oldcode193
Doc/tutorial/introduction.rst:193: are typed for input: inside quotes,
and with quotes and other funny characters
Not entirely true, since the quotes might change.

http://bugs.python.org/review/14097/diff/6689/Doc/tutorial/introduction.rst#oldcode201
Doc/tutorial/introduction.rst:201: next line is a logical continuation
of the line::
This is not the best way to do it IMHO, so I only kept the example with
triple quotes.

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

http://bugs.python.org/review/14097/diff/6689/Doc/tutorial/introduction.rst#newcode27
Doc/tutorial/introduction.rst:27: string = "# This is not a comment
because it's inside quotes."
UPPERCASE is rarely used, so I removed it.
I also explained why this is not a comment.

http://bugs.python.org/review/14097/diff/6689/Doc/tutorial/introduction.rst#newcode61
Doc/tutorial/introduction.rst:61: :class:``float``.  We will see more
about numberic types later in the tutorial.
Added short introduction about int and float.

http://bugs.python.org/review/14097/diff/6689/Doc/tutorial/introduction.rst#newcode63
Doc/tutorial/introduction.rst:63: Classic division (``/``) always return
a float.  To do integer division and get
s/return/returns/.

http://bugs.python.org/review/14097/diff/6689/Doc/tutorial/introduction.rst#newcode65
Doc/tutorial/introduction.rst:65: operator, and to calculate the
remainder you can use ``%``::
This sentence can be improved a bit.
I think it's important to introduce the modulo operator together with
the integer division.

http://bugs.python.org/review/14097/diff/6689/Doc/tutorial/introduction.rst#newcode120
Doc/tutorial/introduction.rst:120: :class:`~fractions.Fraction`.
Here I mentioned other numberic types without going into details.

http://bugs.python.org/review/14097/diff/6689/Doc/tutorial/introduction.rst#newcode130
Doc/tutorial/introduction.rst:130: double quotes (``"..."``) with the
same result.  ``\`` can be used to escape
In other languages '...' and "..." have different meanings, so I added
"with the same result", not sure if this should be more explicit.

http://bugs.python.org/review/14097/diff/6689/Doc/tutorial/introduction.rst#newcode157
Doc/tutorial/introduction.rst:157: >>> s = 'First line.\nSecond line.' 
# \n means newline
Added an example with special characters.

http://bugs.python.org/review/14097/diff/6689/Doc/tutorial/introduction.rst#newcode164
Doc/tutorial/introduction.rst:164: If you don't want to use special
characters, you can use *raw strings* by adding
Is there a glossary entry for this?

http://bugs.python.org/review/14097/diff/6689/Doc/tutorial/introduction.rst#newcode171
Doc/tutorial/introduction.rst:171: C:\some\name
And explain how to use raw strings to avoid unwanted effects.

http://bugs.python.org/review/14097/diff/6689/Doc/tutorial/introduction.rst#newcode193
Doc/tutorial/introduction.rst:193: repeated with ``*``::
This could be moved before the section about """...""", so that
multiline strings created with implicit literal concatenation inside
parentheses can be presented as another alternative.
E.g.:
foo = ("I don't care about the "
       "newlines here.)

http://bugs.python.org/review/14097/diff/6689/Doc/tutorial/introduction.rst#newcode197
Doc/tutorial/introduction.rst:197: >>> 'na '*10 + hero + '!'!
s/!$//

http://bugs.python.org/review/14097/diff/6689/Doc/tutorial/introduction.rst#newcode198
Doc/tutorial/introduction.rst:198: 'na na na na na na na na na na
batman!'
I'm not sure if batman fits in the tutorial.

The HelpAHelpAHelpA example didn't make sense to me (am I missing some
reference?), so I was looking for something word with a repeated
sillable, like banana or ananas, but that only had 2 repetitions.

Since the repeated syllabe was 'na' in both of the cases, I thought
about the popular batman song and used it in the example.  Batman is
also good for 'bat' + 'man' example, and it can be reused in the slicing
section (you can use slices to go from batman to catman to catwoman, or
to extract bat or man, or similar things).
Not sure if that's too much batman for a single page though.

http://bugs.python.org/review/14097/diff/6689/Doc/tutorial/introduction.rst#newcode211
Doc/tutorial/introduction.rst:211: ^
I forgot to show animal + 'man' here.
I changed the previous example because (string) methods have not been
introduced yet.

http://bugs.python.org/review/14097/diff/6689/Doc/tutorial/introduction.rst#newcode225
Doc/tutorial/introduction.rst:225: 'lp'
Here it keeps using the "meaningless" example, so I would change these
too.

http://bugs.python.org/review/14097/diff/6689/Doc/tutorial/introduction.rst#newcode262
Doc/tutorial/introduction.rst:262: Degenerate slice indices are handled
gracefully: an index that is too large is
This should be rephrased, as suggested in the index.

http://bugs.python.org/review/14097/diff/6689/Doc/tutorial/introduction.rst#newcode301
Doc/tutorial/introduction.rst:301: *between* characters, with the left
edge of the first character numbered 0.
For indexes is easier to thing of the indices as pointing *to*
characters though.

http://bugs.python.org/review/14097/diff/6689/Doc/tutorial/introduction.rst#newcode389
Doc/tutorial/introduction.rst:389: b'\xc3\x84pfel'
This section about Unicode should be trimmed down or removed IMHO.  Some
vague reference about Unicode could be done in the string section. 
Encoding/decoding should wait until the bytes type is presented.

http://bugs.python.org/review/14097/diff/6689/Doc/tutorial/introduction.rst#newcode399
Doc/tutorial/introduction.rst:399: have the same type. ::
But usually they do (and should).

http://bugs.python.org/review/14097/diff/6689/Doc/tutorial/introduction.rst#newcode405
Doc/tutorial/introduction.rst:405: Like string indices, list indices
start at 0, and lists can be sliced,
Like string and all other sequences.

http://bugs.python.org/review/14097/diff/6689/Doc/tutorial/introduction.rst#newcode422
Doc/tutorial/introduction.rst:422: means that the following slice
returns a shallow copy of the list *a*::
shallow is not explained.

http://bugs.python.org/review/14097/diff/6689/Doc/tutorial/introduction.rst#newcode432
Doc/tutorial/introduction.rst:432: >>> a[2] = a[2] + 23
I would show a "regular" replacement here, e.g. a[2] = 123

http://bugs.python.org/review/14097/diff/6689/Doc/tutorial/introduction.rst#newcode480
Doc/tutorial/introduction.rst:480: >>> p[1].append('xtra')
Here methods are introduced, without any word about the difference
between methods and functions, and in a somewhat complex example.
Some methods should be introduced already while talking about strings.

http://bugs.python.org/review/14097/diff/6689/Doc/tutorial/introduction.rst#newcode502
Doc/tutorial/introduction.rst:502: >>> while b < 10:
"if" and "for" should be introduced first.
This could be moved to the next page.



Please review this at http://bugs.python.org/review/14097/

Affected files:
  Doc/tutorial/introduction.rst




More information about the docs mailing list