Tutorial 4.7 More on Defining Functions missing screen prompts

[ChasBelov]

BPO	40748
Nosy	@amaajemyfren, @ChasBelov

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2020-05-23.22:27:11.395>
labels = ['3.11', 'type-bug', '3.9', '3.10', 'docs']
title = 'Tutorial 4.7 More on Defining Functions missing screen prompts'
updated_at = <Date 2021-12-01.22:03:06.880>
user = 'https://github.com/ChasBelov'

bugs.python.org fields:

activity = <Date 2021-12-01.22:03:06.880>
actor = 'iritkatriel'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2020-05-23.22:27:11.395>
creator = 'Chas Belov'
dependencies = []
files = []
hgrepos = []
issue_num = 40748
keywords = []
message_count = 9.0
messages = ['369753', '369755', '369761', '369793', '369796', '369823', '369824', '369827', '369894']
nosy_count = 3.0
nosy_names = ['docs@python', 'amaajemyfren', 'Chas Belov']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue40748'
versions = ['Python 3.9', 'Python 3.10', 'Python 3.11']

[ChasBelov]

The tutorial on More on Defining Functions at https://docs.python.org/3.7/tutorial/controlflow.html#more-on-defining-functions is missing most of the >>> and ... screen prompts that show elsewhere in the tutorial. This is potentially confusing to readers.

I am going to attempt a PR by May 26, 2020.

[ChasBelov]

Also in For statements https://docs.python.org/3.10/tutorial/controlflow.html#for-statements (same issue)

[ChasBelov]

Also in For statements https://docs.python.org/3.10/tutorial/controlflow.html#for-statements (same issue)

However, a few of the code blocks having this issue don't exist in the documentation of earlier versions. Do I need a separate issue for each code block that is not common across 3.5 through 3.10? Or would this be handled during the back-porting process?

[amaajemyfren]

On Sun, May 24, 2020 at 2:54 AM Chas Belov <report@bugs.python.org> wrote:

Do I need a separate issue for each code block that is not common across
3.5 through 3.10? Or would this be handled during the back-porting process?

Unless there is an issue, automatic back-porting should handle it.
PR against master(dev/3.10) should be enough.

[amaajemyfren]

Hi @chas Belov,

On Sun, May 24, 2020 at 1:27 AM Chas Belov <report@bugs.python.org> wrote:

The tutorial on More on Defining Functions at https://docs.python.org/3.7/tutorial/controlflow.html#more-on-defining-functions is missing most of the >>> and ... screen prompts that show elsewhere in the tutorial. This is potentially confusing to readers.

I am going to attempt a PR by May 26, 2020.

Are those sections really to be entered in the REPL or could they be
seen as independent code blocks in a file e.g.?
From the dev guide https://devguide.python.org/documenting/#code-examples

The ellipsis for the sys.ps2 secondary interpreter prompt should only be used sparingly,
where it is necessary to clearly differentiate between input lines and output lines.
Besides contributing visual clutter, it makes it difficult for readers to cut-and-paste
examples so they can experiment with variations.

None of those sections has output ... so maybe not put the ellipsis?

[ChasBelov]

@ama Aje My Fren, thank you for the advice re backporting.

As to your points on ..., both good points, and thank you for introducing me to the Documenting Python document, which I will review. While technically the Tutorial is indeed part of Python's documentation, I would argue that the Tutorial is not a place for shorthand. Learning a new language is hard enough without having to also struggle with inconsistencies in the tutorial interface.

My intent with this issue and my (upcoming) pull request is to make the mentioned code blocks consistent with the rest of the page and, indeed, with most of the rest of the tutorial. Most of the tutorial does show >>> and ... at the beginning of each line where the learner would see a prompt. If we are to avoid ... so that learners can copy and paste multiple lines, then why would we not do that through the entire tutorial?

I'm guessing your point is that we only need to show >>> and ... when there will be print output so that we need to distinguish between what is input and what is output. As someone who is currently learning Python, however, consistency in presentation is important to me and reduces cognitive load.

There are other places in the tutorial where code blocks were used for things which are not typed in, or are not typed without other text. Showing >>> and ... for all verbatim input makes it unambiguous as to whether something is to be typed in.

I'll leave it to psychologists as to whether having to type or copy and paste one line at a time leads to better learning.

By REPL, do you mean Read-Eval-Print Loop? I'm not familiar with the acronym and that's what Google is telling me it means. But a Read-Eval-Print Loop would have output, and my understanding is that you are arguing against use of ... when there is no output.

[ChasBelov]

Actually, after reviewing the documentation standards, I will hold off my pull request on this issue and raise the cited section of documentation as a separate issue.

[ChasBelov]

I created new issue For 7.2.7. Code Examples, distinguish between the Tutorial and other documentation https://bugs.python.org/issue40758

[amaajemyfren]

On Sun, May 24, 2020 at 11:34 PM Chas Belov <report@bugs.python.org> wrote:

I'm guessing your point is that we only need to show >>> and ... when there will be print output so that we need to distinguish between what is input and what is output.

Yes, that is my understanding of the devguide.

As someone who is currently learning Python, however, consistency in presentation is important to me and reduces cognitive load.

This is a valid concern, but it may not be the case that all people
will face this issue. More importantly it should be right so the
second time you come back to refresh on a point you can also grasp it
quickly ... no?

By REPL, do you mean Read-Eval-Print Loop? I'm not familiar with the acronym and that's what Google is telling me it means. But a Read-Eval-Print Loop would have output,
and my understanding is that you are arguing against use of ... when there is no output.

Yes - that is the shell of CPython that does the Read-Eval-Print Loop.

My reading of the Docs Dev-quide - and I am not an expert -
discourages the sys.ps1 and sys.ps2 (although the current docs site
can hide them to allow for copy-pasta)