The output of "python -h" is 104 lines long now. It was only 51 lines in 3.6. 35% of it is about the -X option, and 30% about environment variables. Also some lines in the -X option description are too long (102 columns). Both topics are "advanced" and mostly interested for debugging. I suggest to move them out of the main help output.
The are two options:
1. Move it to pydoc topics. The advantage is that it is a standard way, there are already 88 topics. The disadvantage is that this information will be not available in "minimal" installations of Python which do not include docs.
2. Add command-line options like -hX and -henv. The information will always be available with the interpreter, but the interface is special.
On Sat, Dec 18, 2021 at 2:16 PM Serhiy Storchaka storchaka@gmail.com wrote:
The output of "python -h" is 104 lines long now. It was only 51 lines in 3.6. 35% of it is about the -X option, and 30% about environment variables. Also some lines in the -X option description are too long (102 columns). Both topics are "advanced" and mostly interested for debugging. I suggest to move them out of the main help output.
Sounds like a good plan.
The are two options:
- Move it to pydoc topics. The advantage is that it is a standard way,
there are already 88 topics. The disadvantage is that this information will be not available in "minimal" installations of Python which do not include docs.
- Add command-line options like -hX and -henv. The information will
always be available with the interpreter, but the interface is special.
For -X, I suggest we could output the following line:
-X opt : implementation-specific option; use -X help to list options.
We could also see if we can put the help text for each of the supported -X flags in the table defining these flags (sorry, I can't recall where it lives, but I'm pretty sure I've seen such a table.)
For env vars I think moving this to pydoc is fine; I don't think we have a process or mechanism that ensures the docs for env vars are even complete. (We don't have one for the flags either, but somehow I find it hard to conceive of someone adding a new command line flag without them or someone else involved in the code review thinking of updating the help text. But I find it quite conceivable that someone adds a new env var used only in a corner case without anyone thinking to update the docs. And I presume that the -E flag isn't honored 100% of the time either.)
But I wouldn't object to a -h sub-option that lists environment vars either.
On Sat, Dec 18, 2021 at 4:00 PM Guido van Rossum guido@python.org wrote:
On Sat, Dec 18, 2021 at 2:16 PM Serhiy Storchaka storchaka@gmail.com wrote:
The output of "python -h" is 104 lines long now. It was only 51 lines in 3.6. 35% of it is about the -X option, and 30% about environment variables. Also some lines in the -X option description are too long (102 columns). Both topics are "advanced" and mostly interested for debugging. I suggest to move them out of the main help output.
Sounds like a good plan.
The are two options:
- Move it to pydoc topics. The advantage is that it is a standard way,
there are already 88 topics. The disadvantage is that this information will be not available in "minimal" installations of Python which do not include docs.
- Add command-line options like -hX and -henv. The information will
always be available with the interpreter, but the interface is special.
For -X, I suggest we could output the following line:
-X opt : implementation-specific option; use -X help to list options.
+1 from me.
We could also see if we can put the help text for each of the supported -X flags in the table defining these flags (sorry, I can't recall where it lives, but I'm pretty sure I've seen such a table.)
For env vars I think moving this to pydoc is fine; I don't think we have a process or mechanism that ensures the docs for env vars are even complete. (We don't have one for the flags either, but somehow I find it hard to conceive of someone adding a new command line flag without them or someone else involved in the code review thinking of updating the help text. But I find it quite conceivable that someone adds a new env var used only in a corner case without anyone thinking to update the docs. And I presume that the -E flag isn't honored 100% of the time either.)
But I wouldn't object to a -h sub-option that lists environment vars either.
I think an option to `-h` for environment variables is also good as that command can be the generic `-h` output as well without resorting to needing to run Python code like pydoc to get at more help.
On Mon, Dec 20, 2021 at 11:15 AM Brett Cannon brett@python.org wrote:
On Sat, Dec 18, 2021 at 4:00 PM Guido van Rossum guido@python.org wrote:
On Sat, Dec 18, 2021 at 2:16 PM Serhiy Storchaka storchaka@gmail.com wrote:
The output of "python -h" is 104 lines long now. It was only 51 lines in 3.6. 35% of it is about the -X option, and 30% about environment variables. Also some lines in the -X option description are too long (102 columns). Both topics are "advanced" and mostly interested for debugging. I suggest to move them out of the main help output.
Sounds like a good plan.
The are two options:
- Move it to pydoc topics. The advantage is that it is a standard way,
there are already 88 topics. The disadvantage is that this information will be not available in "minimal" installations of Python which do not include docs.
- Add command-line options like -hX and -henv. The information will
always be available with the interpreter, but the interface is special.
For -X, I suggest we could output the following line:
-X opt : implementation-specific option; use -X help to list options.
+1 from me.
We could also see if we can put the help text for each of the supported -X flags in the table defining these flags (sorry, I can't recall where it lives, but I'm pretty sure I've seen such a table.)
For env vars I think moving this to pydoc is fine; I don't think we have a process or mechanism that ensures the docs for env vars are even complete. (We don't have one for the flags either, but somehow I find it hard to conceive of someone adding a new command line flag without them or someone else involved in the code review thinking of updating the help text. But I find it quite conceivable that someone adds a new env var used only in a corner case without anyone thinking to update the docs. And I presume that the -E flag isn't honored 100% of the time either.)
But I wouldn't object to a -h sub-option that lists environment vars either.
I think an option to `-h` for environment variables is also good as that command can be the generic `-h` output as well without resorting to needing to run Python code like pydoc to get at more help.
Fair enough. Quick design proposal:
-h and --help print info about flags (existing flags) --help-env (or --env-help?) prints info about env vars (new flag) -X help prints info about -X options (new -X option)
Two lines printed at the end of the -h/--help output would refer users to --help-env and -Xhelp.
On Dec 20, 2021, at 11:34, Guido van Rossum guido@python.org wrote:
Fair enough. Quick design proposal:
-h and --help print info about flags (existing flags) --help-env (or --env-help?) prints info about env vars (new flag) -X help prints info about -X options (new -X option)
Two lines printed at the end of the -h/--help output would refer users to --help-env and -Xhelp.
+1, and —help-env seems better.
What do you think about -hh (and maybe —help-full) printing full help?
-Barry
On Mon, Dec 20, 2021 at 12:16 PM Barry Warsaw barry@python.org wrote:
On Dec 20, 2021, at 11:34, Guido van Rossum guido@python.org wrote:
Fair enough. Quick design proposal:
-h and --help print info about flags (existing flags) --help-env (or --env-help?) prints info about env vars (new flag) -X help prints info about -X options (new -X option)
Two lines printed at the end of the -h/--help output would refer users
to --help-env and -Xhelp.
+1, and —help-env seems better.
Sure.
What do you think about -hh (and maybe —help-full) printing full help?
Is there enough of a use case for this to bother?
On Dec 20, 2021, at 12:22, Guido van Rossum guido@python.org wrote:
What do you think about -hh (and maybe —help-full) printing full help?
Is there enough of a use case for this to bother?
Maybe not. I’d say if it was easy to implement, why not, but if it’s a pain, don't bother.
-Barry
20.12.21 21:34, Guido van Rossum пише:
Fair enough. Quick design proposal:
-h and --help print info about flags (existing flags) --help-env (or --env-help?) prints info about env vars (new flag) -X help prints info about -X options (new -X option)
Two lines printed at the end of the -h/--help output would refer users to --help-env and -Xhelp.
Thank you Guido and Barry for your suggestions. It looks great!
-
Barry Warsaw -
Brett Cannon -
Guido van Rossum -
Serhiy Storchaka