[Doc-SIG] Python documentation review (fwd)

[Ka-Ping Yee]

... in case you didn't get this the first time.


-- ?!ng

---------- Forwarded message ----------
Date: Fri, 17 Mar 2000 08:19:14 -0600 (CST)
From: Ka-Ping Yee <ping@lfw.org>
To: fdrake@acm.org
Subject: Python documentation review

Hi Fred!

I don't know if you wanted purely technical corrections or
editorial revisions, but i've tried to keep the list down
to small things.  Here we go.  I'm going to use "-" and "+"
to indicate suggested changes (before and after).

I have also marked up these changes in the text itself.  See

    http://crit.org/http://www.python.org/doc/1.5.2p2/tut/

and look for the little red marks.

Here's the tutorial.  Actually, i didn't find much.


*** http://www.python.org/doc/1.5.2p2/tut/node4.html

2.1.2 Interactive Mode

use &nbsp; to keep example prompts on one line, as in:
  - ("<tt class="samp">&gt;&gt;&gt; </tt>")
  + ("<tt class="samp">&gt;&gt;&gt;&nbsp;</tt>")
  - by default three dots ("<tt class="samp">... </tt>").
  + by default three dots ("<tt class="samp">...&nbsp;</tt>").


*** http://www.python.org/doc/1.5.2p2/tut/node5.html

3. An Informal Introduction to Python

first paragraph, same suggestion as above (see 2.1.2)

example "A value can be assigned to several variables simultaneously:"
  - >>> x = y = z = 0  # Zero x, y and z
  + &gt;&gt;&gt; x = y = z = 0  # Assign zero to x, y and z

3.1.2 Strings

example "Unlike a C string, Python strings cannot be changed."
How about adding a suggestion of what you can do here?

  + <p>However, it's easy to just create a new string containing the
  + desired result:
  +
  + <p>
  + <dl><dd><pre class="verbatim">
  + &gt;&gt;&gt; 'x' + word[1:]
  + 'xelpA'
  + &gt;&gt;&gt; 'Splat' + word[-1:]
  + 'SplatA'
  + </pre></dl>





-- ?!ng