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

[chris.jerdonek at gmail.com]

Some random comments (not comprehensive review).


http://bugs.python.org/review/14097/diff/6689/Doc/tutorial/introduction.rst
File Doc/tutorial/introduction.rst (right):

http://bugs.python.org/review/14097/diff/6689/Doc/tutorial/introduction.rst#newcode8
Doc/tutorial/introduction.rst:8: absence of prompts (``>>>`` and
``...``): to repeat the example, you must type
Are you planning to link to glossary entries?  Both ">>>" and "..."
actually appear in the glossary.

http://bugs.python.org/review/14097/diff/6689/Doc/tutorial/introduction.rst#newcode27
Doc/tutorial/introduction.rst:27: string = "# This is not a comment
because it's inside quotes."
I would use a variable name other than "string" so as not to encourage
its use.

http://bugs.python.org/review/14097/diff/6689/Doc/tutorial/introduction.rst#newcode52
Doc/tutorial/introduction.rst:52: >>> 50 - 5*6
Need spaces: 5 * 6 (as well as below)

http://bugs.python.org/review/14097/diff/6689/Doc/tutorial/introduction.rst#newcode146
Doc/tutorial/introduction.rst:146: By default, the interpreter output
the strings inside quotes and keeps other
I would do something like: "By default, the interpreter encloses the
string output in quotes and escapes special characters with
backslashes."  The meaning of the current word ordering is a little
ambiguous: does it output the strings that are inside quotes, or does it
put the strings inside quotes after outputting?  Similarly, does it keep
as is the characters that are escaped by backslashes, or does it escape
with backslashes the funny characters?

http://bugs.python.org/review/14097/diff/6689/Doc/tutorial/introduction.rst#newcode157
Doc/tutorial/introduction.rst:157: >>> s = 'First line.\nSecond line.' 
# \n means newline
On 2012/11/26 17:32:41, ezio.melotti wrote:
> Added an example with special characters.

I would use PEP-8 style for comments, for example by capitalizing the
first letter and ending with a period if the phrase is a sentence
(though the latter is optional for short comments).

http://bugs.python.org/review/14097/diff/6689/Doc/tutorial/introduction.rst#newcode197
Doc/tutorial/introduction.rst:197: >>> 'na '*10 + hero + '!'!
On 2012/11/26 17:32:41, ezio.melotti wrote:
> s/!$//

I would do "10 * 'na '" (add spaces and lead with the number -- as is
customary with polynomials, for example)

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