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

[ezio.melotti at gmail.com]

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
On 2013/05/01 18:30:31, r.david.murray wrote:
> 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.

This could go in a footnote.

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/05/01 18:30:31, r.david.murray wrote:
> 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.

I think this should be presented in the second page, so that people can
first digest what they learned here.
If we put this at the end of the page they might end up reading it while
their brain is still overheating from the amount of information they
just learned and risk to misunderstand it.

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#newcode69
Doc/tutorial/introduction.rst:69: >>>
On 2013/05/01 18:30:31, r.david.murray wrote:
> Why the "blank" line?  i fear the reader will wonder :)

That's because the following 3 commands are related, since they are
basically doing a divmod() and proving that it worked.

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode76
Doc/tutorial/introduction.rst:76: 
On 2013/05/01 18:30:31, r.david.murray wrote:
> I know this is early in the tutorial, but should divmod be mentioned
here?

Maybe in a footnote, functions haven't even be introduced yet, and
divmod() is not really common.

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::
On 2013/05/01 18:30:31, r.david.murray wrote:
> "With Python it is also", but I'm not sure why "also"?  It doesn't
seem to be
> related to the discussion of division.
> 

Most of the other languages only provide the 4 basic operations, but
Python also provides **.

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

That's too advanced/specific for now, I think it could be explained
somewhere else if necessary (or maybe in another footnote?).

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
On 2013/05/01 18:30:31, r.david.murray wrote:
> 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:"

That doesn't sound too well to me.

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
On 2013/05/01 18:30:31, r.david.murray wrote:
> types

OK

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
On 2013/05/01 18:30:31, r.david.murray wrote:
> such as

OK

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
On 2013/05/01 18:30:31, r.david.murray wrote:
> 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.

"with the same result" is supposed to indicate that apart from the
(obvious) differences regarding the escaping of \' and \", they behave
the same.  In other languages there are differences between the two --
e.g. chars like \n and \t and variable interpolation only work with one
kind of quotes.

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode141
Doc/tutorial/introduction.rst:141: 'spam eggs'
On 2013/05/01 18:30:31, r.david.murray wrote:
> I don't think the comments add any value.

They are useful for people who read only the examples, and to link part
of the description with the examples.

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
On 2013/05/01 18:30:31, r.david.murray wrote:
> I would narrow this further, and say "At the command prompt, ...", or
"In the
> interactive interpreter" (shell?) since there really is no "default". 

s/By default/In the interactive interpreter/ SGTM.

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

"In the same way" is not totally accurate, because "s might end up
replaced with 's or the other way around.

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
On 2013/05/01 18:30:31, r.david.murray wrote:
> I would rewrite this as "otherwise it is"

OK

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
On 2013/05/01 18:30:31, r.david.murray wrote:
> I would say "omitting" rather than 'removing'.

OK

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
On 2013/05/01 18:30:31, r.david.murray wrote:
> Rather than "is printed", I would say "the newline produces a new line
in the
> output".

OK

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
On 2013/05/01 18:30:31, r.david.murray wrote:
> "If you don't want characters prefaced by ``\`` to be interpreted as
special
> characters, you can use..."

OK

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
On 2013/05/01 18:30:31, r.david.murray wrote:
> "End of lines are automatically..." This is confusing without the
preceding
> example of escaping the ends of lines in a single quoted string.

This is presented in the next example though.
The idea is that first I introduce """...""" and \ and explain what they
do, then I show an example and its output, pointing out what """..."""
and \ did there.

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

The problem with that is that if people see it, it's likely they are
going to copy it and use it in their code.
Even if \ actually works even outside strings, the examples shows one of
the very few places where it's ok using it (IMHO).

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
On 2013/05/01 18:30:31, r.david.murray wrote:
> comment is redundant.

The reason I added this was to show that those are string literals, even
if indeed it's already mentioned before.

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::
On 2013/05/01 18:30:31, r.david.murray wrote:
> "arbitrary string expressions" is more correct here than "variables".

It's more correct but less clear.  "variables or expressions" might be
OK though.

http://bugs.python.org/review/14097/diff/7743/Doc/tutorial/introduction.rst#newcode213
Doc/tutorial/introduction.rst:213: >>> prefix = 'Py'
On 2013/05/01 18:30:31, r.david.murray wrote:
> 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')

I preferred to show only one example, because each "failing" example
takes 5 more line, and having two tracebacks one after the other might
be confusing.

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.
On 2013/05/01 18:30:31, r.david.murray wrote:
> Perhaps "mathematically" rather than "really"?  Or just drop "really".
 And I'd
> start the sentence with "Because ``-0`` is the same as ``0``..."

OK

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,
On 2013/05/01 18:30:31, r.david.murray wrote:
> 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.

Using the term substring is OK.

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::
On 2013/05/01 18:30:31, r.david.murray wrote:
> I would write this "However, out of range slice indexes are handled
gracefully"

OK

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::
On 2013/05/01 18:30:31, r.david.murray wrote:
> s/can always/should/

OK

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. ::
On 2013/05/01 18:30:31, r.david.murray wrote:
> 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"?

I think it's not necessary, and it's better to keep the tutorial short.

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::
On 2013/05/01 18:30:31, r.david.murray wrote:
> We probably ought to link this to "shallow copy" in the glossary...and
make an
> entry for it :)

OK (was there an issue for this?)

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