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

chris.jerdonek at gmail.com chris.jerdonek at gmail.com
Mon Nov 26 19:58:19 CET 2012

Some random comments (not comprehensive review).

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

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.

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.

Doc/tutorial/introduction.rst:52: >>> 50 - 5*6
Need spaces: 5 * 6 (as well as below)

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?

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

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)


More information about the docs mailing list