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

rdmurray at bitdance.com rdmurray at bitdance.com
Wed May 8 14:23:56 CEST 2013

On 2013/05/01 22:50:41, ezio.melotti wrote:
> Doc/tutorial/introduction.rst:110: Complex numbers are also supported;
> 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.

Because it is part of the language syntax I think there should be at
least a one line mention in the main text.  It could then have a 'for
more information' link.

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

That seems fine, if you also move the [:] example to that page.

> 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
> Maybe in a footnote, functions haven't even be introduced yet, and
divmod() is
> not really common.

Probably even a footnote isn't appropriate.

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

Without having created that context for 'also' in the text, I think it
be better to just drop it.

> > 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
> else if necessary (or maybe in another footnote?).

A footnote would be fine.

> 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
> > 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
> That doesn't sound too well to me.

What about it doesn't sound good?  "defined" just feels *wrong* to me

> Doc/tutorial/introduction.rst:137: double quotes (``"..."``) with the
> 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
> "with the same result" is supposed to indicate that apart from the
> 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.

How about putting that note that other languages do make distinctions
in a footnote?  (Or as a separate sentence.)

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

OK.  I don't like them personally, but I can deal with that as personal

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

That's why my suggested replacement uses the word "could" :)

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

Right, and I'm saying that I don't think that exposition works as well.

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

The text linking the two examples can say that the second one is the
way to do it.

> 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
> It's more correct but less clear.  "variables or expressions" might be
> though.

That sounds fine.

> 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

You could use the '...' notation and only show the SyntaxError.  That
be typographically clear even to a beginner.

> 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
> > type.  How about having both examples, and prefacing the second one
> > "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

Well, I still think you are losing something valuable, but I won't block
on it

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

I don't think so.


More information about the docs mailing list