classification
Title: error in tutorial triple-string example
Type: Stage: resolved
Components: Documentation Versions: Python 3.1, Python 3.2
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, ezio.melotti, maltehelmert, r.david.murray, terry.reedy
Priority: normal Keywords: easy, patch

Created on 2010-11-04 00:28 by maltehelmert, last changed 2010-11-12 04:36 by terry.reedy. This issue is now closed.

Files
File name Uploaded Description Edit
Issue 10304.diff terry.reedy, 2010-11-12 04:36 Fix endings
Messages (8)
msg120364 - (view) Author: Malte Helmert (maltehelmert) Date: 2010-11-04 00:28
From Section 3.1.2 of the tutorial:

  print("""
  Usage: thingy [OPTIONS]
       -h                        Display this usage message
       -H hostname               Hostname to connect to
  """)

  produces the following output:

  _____________________________________________________________
  Usage: thingy [OPTIONS]
       -h                        Display this usage message
       -H hostname               Hostname to connect to
  _____________________________________________________________


That doesn't quite match the behaviour: there should be an extra blank line prepended to the output.
msg120365 - (view) Author: Malte Helmert (maltehelmert) Date: 2010-11-04 00:44
Here's a related one if you want to get the sample output really 100% correct. In the last example of Section 3, the output in

{>>> a, b = 0, 1
>>> while b < 1000:
...     print(b, end=' ')
...     a, b = b, a+b
...
1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987}

should have an extra space at the end. (Granted, this is very very minor, but this may make a Python 2.x oldtimer like me wonder if print's end=" " does the same as old Python 2.x's "print b," including suppression of the "softspace".)
msg120548 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2010-11-05 22:28
1. Rather than add a blank line to the output, the input should have the newline suppressed with \ (which has been done in previous examples).
  print("""\

2. It is rather difficult to see that there is no blank at the end (highlight with mouse). I can imagine that either the formatter or display system might delete even if in the master .rst file. In interactive use, the interpreter will go to a new line anyway before printing the >>> prompt.

The intent and effect of end=' ' is that the outputs are all on one line (as with 2.x print) instead of each on a separate line
msg120550 - (view) Author: Malte Helmert (maltehelmert) Date: 2010-11-05 22:37
> 1. Rather than add a blank line to the output, the input should have
> the newline suppressed with \ (which has been done in previous
> examples).
> print("""\

I think that would be didactically bad after just mentioning that newlines in triple-quoted strings don't have to be escaped etc.
I think this would confuse the reader.

Better use print("""Usage...


> In interactive use, the interpreter will go to a new line anyway
> before printing the >>> prompt.

It won't (at least in Python 3.1). I just tried it.

> The intent and effect of end=' ' is that the outputs are all on one
> line (as with 2.x print) instead of each on a separate line

Sure. But I think that in an example that is essentially about whitespace produced by print, the actual whitespace in the output should match the actual behaviour of print. One why to get rid of this problem altogether is to add a 'print "done!"' or whatever at the end, or use a different separator from " ".
msg120552 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2010-11-05 23:01
I think the commit hook might object to the trailing blank (I'm not sure it applies to rst files, but I think it does).
msg120572 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2010-11-06 02:55
I should have said that IDLE puts >>> on a new line.
msg120625 - (view) Author: Malte Helmert (maltehelmert) Date: 2010-11-06 15:22
I see. (The tutorial really talks about the interactive interpreter though -- I don't think IDLE has been mentioned yet.)
msg121018 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2010-11-12 04:36
1. I decided to add '\' since this is what I normally do and also add one sentence explanation.

2. I changed ending from ' ' to ','.

Uploaded patch committed in rev86422, rev86423
History
Date User Action Args
2010-11-12 04:36:27terry.reedysetstatus: open -> closed
files: + Issue 10304.diff

versions: + Python 3.1
keywords: + patch
resolution: fixed
messages: + msg121018
stage: needs patch -> resolved
2010-11-06 15:22:36maltehelmertsetmessages: + msg120625
2010-11-06 02:55:04terry.reedysetmessages: + msg120572
2010-11-05 23:01:30r.david.murraysetnosy: + r.david.murray
messages: + msg120552
2010-11-05 22:37:17maltehelmertsetmessages: + msg120550
2010-11-05 22:29:12terry.reedysetkeywords: + easy
2010-11-05 22:28:56terry.reedysetnosy: + terry.reedy

messages: + msg120548
stage: needs patch
2010-11-04 00:44:08maltehelmertsetmessages: + msg120365
2010-11-04 00:30:19ezio.melottisetnosy: + ezio.melotti
2010-11-04 00:28:22maltehelmertcreate