[issue40748] Tutorial 4.7 More on Defining Functions missing screen prompts
New submission from Chas Belov <docorbit@sonic.net>: The tutorial on More on Defining Functions at https://docs.python.org/3.7/tutorial/controlflow.html#more-on-defining-funct... 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 <report@bugs.python.org> <https://bugs.python.org/issue40748> _______________________________________
Chas Belov <docorbit@sonic.net> added the comment: Also in For statements https://docs.python.org/3.10/tutorial/controlflow.html#for-statements (same issue) ---------- title: Tutorial 4.7 More on Defining Functions missing screen prompts -> Tutorial 4 More Control Flow Tools missing screen prompts in some code blocks _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue40748> _______________________________________
Chas Belov <docorbit@sonic.net> added the comment: 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? ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue40748> _______________________________________
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.
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-funct... 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?
Chas Belov <docorbit@sonic.net> 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 <report@bugs.python.org> <https://bugs.python.org/issue40748> _______________________________________
Ama Aje My Fren <amaajemyfren@gmail.com> added the comment: 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) ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue40748> _______________________________________
Chas Belov <docorbit@sonic.net> 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 <report@bugs.python.org> <https://bugs.python.org/issue40748> _______________________________________
Chas Belov <docorbit@sonic.net> 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 <report@bugs.python.org> <https://bugs.python.org/issue40748> _______________________________________
participants (3)
-
Ama Aje My Fren -
Ama Aje My Fren -
Chas Belov