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

rdmurray at bitdance.com rdmurray at bitdance.com
Wed May 1 18:30:31 CEST 2013


Sorry, Ezio, I do have comments :)


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#oldcode110
Doc/tutorial/introduction.rst:110: Complex numbers are also supported;
imaginary numbers are written with a suffix
The problem with completely omitting this is that the 'j' notation is a
special feature of the syntax, unlike Decimal or Fraction, which are
"just" specialized classes.

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.
On 2013/04/02 01:19:18, ezio.melotti wrote:
> 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.

I think maybe you could (should) cover it at an *earlier* point, in the
discussion of [:] and what makes it a copy.

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#newcode63
Doc/tutorial/introduction.rst:63: Classic division (``/``) always
returns a float.  To do integer division and
"Classic" sounds wrong here.  Perhaps "normal" (as opposed to
"integer")?

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode69
Doc/tutorial/introduction.rst:69: >>>
Why the "blank" line?  i fear the reader will wonder :)

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode76
Doc/tutorial/introduction.rst:76: 
I know this is early in the tutorial, but should divmod be mentioned
here?

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode77
Doc/tutorial/introduction.rst:77: With Python is also possible to use
the ``**`` operator to calculate powers::
"With Python it is also", but I'm not sure why "also"?  It doesn't seem
to be related to the discussion of division.

The other problem with introducing ** here is that any discussion of **
should include a discussion of operator precedence and why -1**2 == -1.

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode84
Doc/tutorial/introduction.rst:84: The equal sign (``'='``) is used to
assign a value to a variable. Afterwards, no
I agree with the comments in the issue that 'name' should be used
instead of variable, but that can be a separate patch :)

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode92
Doc/tutorial/introduction.rst:92: If a variable is not "defined"
(assigned a value), trying to use it will
I really don't like the use of the word 'defined' here.  I'd prefer
something like "A name must be assigned an initial value before it can
be used.  Trying to use a name that hasn't been assigned a value will
give you an error:"

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode125
Doc/tutorial/introduction.rst:125: In addition to :class:`int` and
:class:`float`, Python supports other type of
types

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode126
Doc/tutorial/introduction.rst:126: numbers, like :class:`complex`,
:class:`~decimal.Decimal`, and
such as

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode137
Doc/tutorial/introduction.rst:137: double quotes (``"..."``) with the
same result.  ``\`` can be used to escape
I'm not sure "with the same result" is at all clear, here.  I think it
would be better to just say "They can be enclosed in either single
quotes (``'...''') or double quotes (``"..."``)" and then have the next
sentence read "``\`` can be used to escape a quote character in a string
that is surrounded by that same type of quote character::" which the
examples with then make concrete.

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode141
Doc/tutorial/introduction.rst:141: 'spam eggs'
I don't think the comments add any value.

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode153
Doc/tutorial/introduction.rst:153: By default, the interpreter encloses
the string output in quotes and escapes special characters with
backslashes.  The string is enclosed in
I would narrow this further, and say "At the command prompt, ...", or
"In the interactive interpreter" (shell?) since there really is no
"default".  I also would prefer to retain the sense of the 'in the same
way' phrase...perhaps "in a way that they could be typed at the input
prompt"?

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode154
Doc/tutorial/introduction.rst:154: double quotes if the string contains
a single quote and no double quotes, else
I would rewrite this as "otherwise it is"

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode156
Doc/tutorial/introduction.rst:156: readable output, by removing the
enclosing quotes and by printing escaped and
I would say "omitting" rather than 'removing'.

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode166
Doc/tutorial/introduction.rst:166: >>> print(s)  # with print(), the
newline is printed
Rather than "is printed", I would say "the newline produces a new line
in the output".

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode170
Doc/tutorial/introduction.rst:170: If you don't want to use special
characters, you can use *raw strings* by adding
"If you don't want characters prefaced by ``\`` to be interpreted as
special characters, you can use..."

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode179
Doc/tutorial/introduction.rst:179: String literals can span multiple
lines in several ways.  One way is using
You say "several ways" but then only discuss one of them.  Probably just
drop the "several ways"...although, see next note.

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode180
Doc/tutorial/introduction.rst:180: triple-quotes: ``"""..."""`` or
``'''...'''``.  End of lines are automatically
"End of lines are automatically..." This is confusing without the
preceding example of escaping the ends of lines in a single quoted
string.  That section should be retained, IMO. Despite the fact that it
is not "best practice" to write code that way, pedagogically it explains
the concepts better.

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode190
Doc/tutorial/introduction.rst:190: produces the following output (note
that the initial newline is not included):
I think the original exposition ("So the following example uses one
escape to avoid an unwanted initial blank line") is better than this
comment.

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode208
Doc/tutorial/introduction.rst:208: >>> 'Py' 'thon'  # these string
literals are concatenated automatically
comment is redundant.

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode211
Doc/tutorial/introduction.rst:211: This only works with two literals
though, not with variables::
"arbitrary string expressions" is more correct here than "variables".

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode213
Doc/tutorial/introduction.rst:213: >>> prefix = 'Py'
I think you should include an expression example as well, such as
showing that the multiplication example doesn't work with string
concatenation.  (But you should reverse it, 'un' *3 'ium')

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode252
Doc/tutorial/introduction.rst:252: Note that since -0 is really the same
as 0, negative indices start from -1.
Perhaps "mathematically" rather than "really"?  Or just drop "really". 
And I'd start the sentence with "Because ``-0`` is the same as ``0``..."

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode254
Doc/tutorial/introduction.rst:254: In addition to indexing, *slicing* is
also supported. As the name says,
Here again I prefer the original exposition, though we should drop the
reference to the Icon programming language.  I think most people will
know what a "substring" is, and if they don't the example will quickly
make it clear.

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode262
Doc/tutorial/introduction.rst:262: Note how the start is always
included, and the end always excluded.  This
This is a good addition, though.

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
On 2013/04/02 01:19:18, ezio.melotti wrote:
> 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?

I don't think so.  We are talking about slicing here. indexing is very
straightforward, so I don't think not mentioning it here will confuse
anyone.

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode307
Doc/tutorial/introduction.rst:307: However these values are handled
gracefully when used for slicing::
I would write this "However, out of range slice indexes are handled
gracefully"

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode312
Doc/tutorial/introduction.rst:312: ''
You should include the -100 slice example here as well, as well as the
[2:1] example...which probably means you need to reintroduce the
sentence about what is actually done with the out of range indexes.

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode326
Doc/tutorial/introduction.rst:326: If you need a different string, you
can always create a new one::
s/can always/should/

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode367
Doc/tutorial/introduction.rst:367: items of different types, but usually
the items all have the same type. ::
You are losing something here by omitting the example of items of
different type.  How about having both examples, and prefacing the
second one with, "Normally, however, lists elements will all be of the
same type"?

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode384
Doc/tutorial/introduction.rst:384: means that the following slice
returns a new (shallow) copy of the list::
We probably ought to link this to "shallow copy" in the glossary...and
make an entry for it :)

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode387
Doc/tutorial/introduction.rst:387: [1, 2, 4, 9, 16, 25]
It would be nice to show what it means that this is a copy...which I
think means moving this bit down below the demonstration of the fact
that lists are mutable.

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode411
Doc/tutorial/introduction.rst:411: 
[:] as copy could go here.

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


More information about the docs mailing list