cpython icon indicating copy to clipboard operation
cpython copied to clipboard

Tutorial: command for `python -c` should be consistent with main command

Open encukou opened this issue 2 years ago • 7 comments

encukou avatar Nov 16 '23 10:11 encukou

In https://docs.python.org/3/tutorial/interpreter.html, the main command is python3.12 but later an alternative is given: python -c command [arg] ... Both should be the same (python3.12).

encukou avatar Nov 16 '23 10:11 encukou

I disagree. Explain that since the actual command word needed or allowed varies by OS and installation, we use the generic 'python' except in literal code examples where something more specific is needed, and that users should interpret 'python' as needed. It might be good to explain that a now generic 'python3' may also work to get the 'latest' python3.x.

terryjreedy avatar Nov 16 '23 20:11 terryjreedy

The initial statement "The Python interpreter is usually installed as /usr/local/bin/python3.12 on those machines where it is available" is unix specific and is both wrong and meaningless for the majority of beginners, the presumed target of the tutorial. Version specific statement should explicitly say so. Start with "The Python 3.12 interpreter ..." whatever the continuation.

The box with "python3.12" is wrong for Windows users who install from python.org (and maybe other places other than Microsoft store) and install the recommended way, which is to use the py launcher and not add the python3.12 directory to PATH. I believe that a majority of beginners are using Windows releases and therefore think the tutorial should not treat them as an afterthought.

terryjreedy avatar Nov 16 '23 20:11 terryjreedy

A deeper problem is that 'Invoking the interpreter' only discusses starting Python from a command line, which may the the least common way beginners start Python. It ignores icons, menus, and file dialogs.

terryjreedy avatar Nov 17 '23 00:11 terryjreedy

I believe that a majority of beginners are using Windows releases and therefore think the tutorial should not treat them as an afterthought.

We have numbers that suggest this. From the Plausible trial in July, 58.6% of visitors to the docs used Windows.

We don't know if they were beginners or tutorial visitors, but tutorial pages are amongst the most visited, so I expect many are also Windows users:

hugovk avatar Nov 17 '23 07:11 hugovk

Is the issue now about updating the tutorial to help Windows users? I believe that issue is different than what the title says. I believe the original issue stated original title no longer an issue as I can not find the inconsistency. Should the title be changed to add a tutorial information for Windows users, or create a new issue?

drts01 avatar May 20 '24 16:05 drts01

The inconsistency reported by a user, between python3.12 and python, is still there. The fixup needed in more complicated then replacing either by the other. I have changed the title. I am thinking about a draft PR.

terryjreedy avatar May 20 '24 16:05 terryjreedy