[issue40748] Tutorial 4.7 More on Defining Functions missing screen prompts

[Irit Katriel]

Change by Irit Katriel :


--
type:  -> behavior
versions: +Python 3.11 -Python 3.5, Python 3.6, Python 3.7, Python 3.8

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40748] Tutorial 4.7 More on Defining Functions missing screen prompts

[Ama Aje My Fren]

Ama Aje My Fren  added the comment:

On Sun, May 24, 2020 at 11:34 PM Chas Belov  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)

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40748] Tutorial 4.7 More on Defining Functions missing screen prompts

[Chas Belov]

Chas Belov  added the comment:

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

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40748] Tutorial 4.7 More on Defining Functions missing screen prompts

[Chas Belov]

Chas Belov  added the comment:

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40748] Tutorial 4.7 More on Defining Functions missing screen prompts

[Chas Belov]

Chas Belov  added the comment:

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

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40748] Tutorial 4.7 More on Defining Functions missing screen prompts

[Ama Aje My Fren]

Ama Aje My Fren  added the comment:

Hi @Chas Belov,

On Sun, May 24, 2020 at 1:27 AM Chas Belov  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?

--
title: Tutorial 4 More Control Flow Tools missing screen prompts in some code 
blocks -> Tutorial 4.7 More on Defining Functions missing screen prompts

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40748] Tutorial 4.7 More on Defining Functions missing screen prompts

[Chas Belov]

New submission from Chas Belov :

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.

--
assignee: docs@python
components: Documentation
messages: 369753
nosy: Chas Belov, docs@python
priority: normal
severity: normal
status: open
title: Tutorial 4.7 More on Defining Functions missing screen prompts
versions: Python 3.10, Python 3.5, Python 3.6, Python 3.7, Python 3.8, Python 
3.9

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com