[Python-Dev] Re: The python command help is too long

[Barry Warsaw]

On Dec 20, 2021, at 12:22, Guido van Rossum  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



signature.asc
Description: Message signed with OpenPGP
___
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-le...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/python-dev@python.org/message/T66U3KWST6OQQS37FAX3VXULC3O6GAVB/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Re: The python command help is too long

[Serhiy Storchaka]

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!

___
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-le...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/python-dev@python.org/message/7PL3GAK26HXX3PLFU6MSHNUHKOYE3D7G/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Re: The python command help is too long

[Guido van Rossum]

On Mon, Dec 20, 2021 at 12:16 PM Barry Warsaw  wrote:

> On Dec 20, 2021, at 11:34, Guido van Rossum  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?

-- 
--Guido van Rossum (python.org/~guido)
*Pronouns: he/him **(why is my pronoun here?)*

___
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-le...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/python-dev@python.org/message/BSCJIDR4BJYB2OZH7EU4NOKBFYFZIFBT/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Re: The python command help is too long

[Barry Warsaw]

On Dec 20, 2021, at 11:34, Guido van Rossum  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



signature.asc
Description: Message signed with OpenPGP
___
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-le...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/python-dev@python.org/message/BJVQBZSBRJU74NWUYPQCHVGL42MT6W7Z/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Re: The python command help is too long

[Guido van Rossum]

On Mon, Dec 20, 2021 at 11:15 AM Brett Cannon  wrote:

>
>
> On Sat, Dec 18, 2021 at 4:00 PM Guido van Rossum  wrote:
>
>> On Sat, Dec 18, 2021 at 2:16 PM Serhiy Storchaka 
>> 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:
>>>
>>> 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.
>>>
>>
>> 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.

-- 
--Guido van Rossum (python.org/~guido)
*Pronouns: he/him **(why is my pronoun here?)*

___
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-le...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/python-dev@python.org/message/NF4LTZWAMOATEA4ZZLIGVIJOATVIYMF2/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Re: The python command help is too long

[Brett Cannon]

On Sat, Dec 18, 2021 at 4:00 PM Guido van Rossum  wrote:

> On Sat, Dec 18, 2021 at 2:16 PM Serhiy Storchaka 
> 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:
>>
>> 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.
>>
>
> 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.
___
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-le...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/python-dev@python.org/message/BSXEPG6ERPYCPPQ6WVAF3NJU5CVFFJ4Y/
Code of Conduct: http://python.org/psf/codeofconduct/

[Python-Dev] Re: The python command help is too long

[Guido van Rossum]

On Sat, Dec 18, 2021 at 2:16 PM Serhiy Storchaka 
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:
>
> 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.
>

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.

-- 
--Guido van Rossum (python.org/~guido)
*Pronouns: he/him **(why is my pronoun here?)*

___
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-le...@python.org
https://mail.python.org/mailman3/lists/python-dev.python.org/
Message archived at 
https://mail.python.org/archives/list/python-dev@python.org/message/Q7OUIDUMTDLLOFAGZHZZJLW4HAYLBYBF/
Code of Conduct: http://python.org/psf/codeofconduct/