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

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#... 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#... Doc/tutorial/introduction.rst:551: object! We'll come back to *object semantics* later. On 2013/04/02 01:19:18, ezio.melotti wrote: 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#... 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#... 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#... 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#... 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#... 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#... 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#... 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#... 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#... 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#... 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#... 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#... 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#... 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#... 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#... 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#... 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#... 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#... 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#... 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#... 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#... 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#... 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#... 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#... 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#... 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#... 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#... 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#... 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#... 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#... 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#... 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#... Doc/tutorial/introduction.rst:411: [:] as copy could go here. http://bugs.python.org/review/14097/