[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 :)

File Doc/tutorial/introduction.rst (left):

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.

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

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

File Doc/tutorial/introduction.rst (right):

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

Doc/tutorial/introduction.rst:69: >>>
Why the "blank" line?  i fear the reader will wonder :)

I know this is early in the tutorial, but should divmod be mentioned

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.

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 :)

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:"

Doc/tutorial/introduction.rst:125: In addition to :class:`int` and
:class:`float`, Python supports other type of

Doc/tutorial/introduction.rst:126: numbers, like :class:`complex`,
:class:`~decimal.Decimal`, and
such as

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.

Doc/tutorial/introduction.rst:141: 'spam eggs'
I don't think the comments add any value.

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

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"

Doc/tutorial/introduction.rst:156: readable output, by removing the
enclosing quotes and by printing escaped and
I would say "omitting" rather than 'removing'.

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".

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..."

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.

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.

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

Doc/tutorial/introduction.rst:208: >>> 'Py' 'thon'  # these string
literals are concatenated automatically
comment is redundant.

Doc/tutorial/introduction.rst:211: This only works with two literals
though, not with variables::
"arbitrary string expressions" is more correct here than "variables".

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')

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``..."

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.

Doc/tutorial/introduction.rst:262: Note how the start is always
included, and the end always excluded.  This
This is a good addition, though.

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

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

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.

Doc/tutorial/introduction.rst:326: If you need a different string, you
can always create a new one::
s/can always/should/

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"?

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 :)

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.

[:] as copy could go here.


More information about the docs mailing list