Patchwork [V2] help: hide command line options marked as "advanced"

login
register
mail settings
Submitter Jun Wu
Date Nov. 1, 2016, 3:08 p.m.
Message ID <058074cf24ce30ee0bc6.1478012936@x1c>
Download mbox | patch
Permalink /patch/17243/
State Changes Requested
Headers show

Comments

Jun Wu - Nov. 1, 2016, 3:08 p.m.
# HG changeset patch
# User Jun Wu <quark@fb.com>
# Date 1478011845 0
#      Tue Nov 01 14:50:45 2016 +0000
# Node ID 058074cf24ce30ee0bc6d6a4d91fbe35631f8e8e
# Parent  264f00b3e5f045ac5b58d79e2a3976585f4e7739
# Available At https://bitbucket.org/quark-zju/hg-draft
#              hg pull https://bitbucket.org/quark-zju/hg-draft -r 058074cf24ce
help: hide command line options marked as "advanced"

Previously, we have keywords like "(DEPRECATED)" and "(EXPERIMENTAL)" to
hide command line options in non-verbose help output.

However, sometimes an option is neither deprecated nor experimental. It's
well-tested and working, but just not designed to average users. This patch
adds a keyword "(ADVANCED)" to fit in such use cases.

Thanks rom1dep for the suggestion of the word "advanced".
Pierre-Yves David - Nov. 1, 2016, 11:41 p.m.
On 11/01/2016 04:08 PM, Jun Wu wrote:
> # HG changeset patch
> # User Jun Wu <quark@fb.com>
> # Date 1478011845 0
> #      Tue Nov 01 14:50:45 2016 +0000
> # Node ID 058074cf24ce30ee0bc6d6a4d91fbe35631f8e8e
> # Parent  264f00b3e5f045ac5b58d79e2a3976585f4e7739
> # Available At https://bitbucket.org/quark-zju/hg-draft
> #              hg pull https://bitbucket.org/quark-zju/hg-draft -r 058074cf24ce
> help: hide command line options marked as "advanced"
>
> Previously, we have keywords like "(DEPRECATED)" and "(EXPERIMENTAL)" to
> hide command line options in non-verbose help output.
>
> However, sometimes an option is neither deprecated nor experimental. It's
> well-tested and working, but just not designed to average users. This patch
> adds a keyword "(ADVANCED)" to fit in such use cases.
>
> Thanks rom1dep for the suggestion of the word "advanced".

Do we have any candidate for this in core ?

We probably need to hint the fact we have more to show here. Having 
verbose section display a note about it, we should have the same here.

> diff --git a/mercurial/help.py b/mercurial/help.py
> --- a/mercurial/help.py
> +++ b/mercurial/help.py
> @@ -34,12 +34,15 @@ from .hgweb import (
>  )
>
> -_exclkeywords = [
> +_exclkeywords = set([
> +    "(ADVANCED)",
>      "(DEPRECATED)",
>      "(EXPERIMENTAL)",
> +    # i18n: "(ADVANCED)" is a keyword, must be translated consistently
> +    _("(ADVANCED)"),
>      # i18n: "(DEPRECATED)" is a keyword, must be translated consistently
>      _("(DEPRECATED)"),
>      # i18n: "(EXPERIMENTAL)" is a keyword, must be translated consistently
>      _("(EXPERIMENTAL)"),
> -    ]
> +    ])
>
>  def listexts(header, exts, indent=1, showdeprecated=False):
> diff --git a/tests/test-help.t b/tests/test-help.t
> --- a/tests/test-help.t
> +++ b/tests/test-help.t
> @@ -684,4 +684,5 @@ this is a section and erroring out weird
>    >     'hg nohelp',
>    >     norepo=True)
> +  > @command('debugoptADV', [('', 'aopt', None, 'option is (ADVANCED)')])
>    > @command('debugoptDEP', [('', 'dopt', None, 'option is (DEPRECATED)')])
>    > @command('debugoptEXP', [('', 'eopt', None, 'option is (EXPERIMENTAL)')])
> @@ -897,4 +898,5 @@ Test list of internal help commands
>     debugobsolete
>                   create arbitrary obsolete marker
> +   debugoptADV   (no help text available)
>     debugoptDEP   (no help text available)
>     debugoptEXP   (no help text available)
> @@ -1108,5 +1110,13 @@ Test list of commands with command with
>
>
> -test deprecated and experimental options are hidden in command help
> +test advanced, deprecated and experimental options are hidden in command help
> +  $ hg help debugoptADV
> +  hg debugoptADV
> +
> +  (no help text available)
> +
> +  options:
> +
> +  (some details hidden, use --verbose to show complete help)
>    $ hg help debugoptDEP
>    hg debugoptDEP
> @@ -1127,5 +1137,7 @@ test deprecated and experimental options
>    (some details hidden, use --verbose to show complete help)
>
> -test deprecated and experimental options is shown with -v
> +test advanced, deprecated and experimental options are shown with -v
> +  $ hg help -v debugoptADV | grep aopt
> +    --aopt option is (ADVANCED)
>    $ hg help -v debugoptDEP | grep dopt
>      --dopt option is (DEPRECATED)
> _______________________________________________
> Mercurial-devel mailing list
> Mercurial-devel@mercurial-scm.org
> https://www.mercurial-scm.org/mailman/listinfo/mercurial-devel
>
Jun Wu - Nov. 1, 2016, 11:49 p.m.
Excerpts from Pierre-Yves David's message of 2016-11-02 00:41:03 +0100:
> 
> On 11/01/2016 04:08 PM, Jun Wu wrote:
> > # HG changeset patch
> > # User Jun Wu <quark@fb.com>
> > # Date 1478011845 0
> > #      Tue Nov 01 14:50:45 2016 +0000
> > # Node ID 058074cf24ce30ee0bc6d6a4d91fbe35631f8e8e
> > # Parent  264f00b3e5f045ac5b58d79e2a3976585f4e7739
> > # Available At https://bitbucket.org/quark-zju/hg-draft 
> > #              hg pull https://bitbucket.org/quark-zju/hg-draft  -r 058074cf24ce
> > help: hide command line options marked as "advanced"
> >
> > Previously, we have keywords like "(DEPRECATED)" and "(EXPERIMENTAL)" to
> > hide command line options in non-verbose help output.
> >
> > However, sometimes an option is neither deprecated nor experimental. It's
> > well-tested and working, but just not designed to average users. This patch
> > adds a keyword "(ADVANCED)" to fit in such use cases.
> >
> > Thanks rom1dep for the suggestion of the word "advanced".
> 
> Do we have any candidate for this in core ?

It should be better than "(VERBOSE)".

> We probably need to hint the fact we have more to show here. Having 
> verbose section display a note about it, we should have the same here.

It currently displays the same way as other keywords:
"(some details hidden, use --verbose to show complete help)".
That's included in the .t change below.

Do you mean a different hint text? I don't think it's that useful.

> > diff --git a/mercurial/help.py b/mercurial/help.py
> > --- a/mercurial/help.py
> > +++ b/mercurial/help.py
> > @@ -34,12 +34,15 @@ from .hgweb import (
> >  )
> >
> > -_exclkeywords = [
> > +_exclkeywords = set([
> > +    "(ADVANCED)",
> >      "(DEPRECATED)",
> >      "(EXPERIMENTAL)",
> > +    # i18n: "(ADVANCED)" is a keyword, must be translated consistently
> > +    _("(ADVANCED)"),
> >      # i18n: "(DEPRECATED)" is a keyword, must be translated consistently
> >      _("(DEPRECATED)"),
> >      # i18n: "(EXPERIMENTAL)" is a keyword, must be translated consistently
> >      _("(EXPERIMENTAL)"),
> > -    ]
> > +    ])
> >
> >  def listexts(header, exts, indent=1, showdeprecated=False):
> > diff --git a/tests/test-help.t b/tests/test-help.t
> > --- a/tests/test-help.t
> > +++ b/tests/test-help.t
> > @@ -684,4 +684,5 @@ this is a section and erroring out weird
> >    >     'hg nohelp',
> >    >     norepo=True)
> > +  > @command('debugoptADV', [('', 'aopt', None, 'option is (ADVANCED)')])
> >    > @command('debugoptDEP', [('', 'dopt', None, 'option is (DEPRECATED)')])
> >    > @command('debugoptEXP', [('', 'eopt', None, 'option is (EXPERIMENTAL)')])
> > @@ -897,4 +898,5 @@ Test list of internal help commands
> >     debugobsolete
> >                   create arbitrary obsolete marker
> > +   debugoptADV   (no help text available)
> >     debugoptDEP   (no help text available)
> >     debugoptEXP   (no help text available)
> > @@ -1108,5 +1110,13 @@ Test list of commands with command with
> >
> >
> > -test deprecated and experimental options are hidden in command help
> > +test advanced, deprecated and experimental options are hidden in command help
> > +  $ hg help debugoptADV
> > +  hg debugoptADV
> > +
> > +  (no help text available)
> > +
> > +  options:
> > +
> > +  (some details hidden, use --verbose to show complete help)

^^ Here is the hint.

> >    $ hg help debugoptDEP
> >    hg debugoptDEP
> > @@ -1127,5 +1137,7 @@ test deprecated and experimental options
> >    (some details hidden, use --verbose to show complete help)
> >
> > -test deprecated and experimental options is shown with -v
> > +test advanced, deprecated and experimental options are shown with -v
> > +  $ hg help -v debugoptADV | grep aopt
> > +    --aopt option is (ADVANCED)
> >    $ hg help -v debugoptDEP | grep dopt
> >      --dopt option is (DEPRECATED)
> > https://www.mercurial-scm.org/mailman/listinfo/mercurial-devel 
> >
>
Pierre-Yves David - Nov. 2, 2016, 1:52 a.m.
On 11/02/2016 12:49 AM, Jun Wu wrote:
> Excerpts from Pierre-Yves David's message of 2016-11-02 00:41:03 +0100:
>>
>> On 11/01/2016 04:08 PM, Jun Wu wrote:
>>> # HG changeset patch
>>> # User Jun Wu <quark@fb.com>
>>> # Date 1478011845 0
>>> #      Tue Nov 01 14:50:45 2016 +0000
>>> # Node ID 058074cf24ce30ee0bc6d6a4d91fbe35631f8e8e
>>> # Parent  264f00b3e5f045ac5b58d79e2a3976585f4e7739
>>> # Available At https://bitbucket.org/quark-zju/hg-draft
>>> #              hg pull https://bitbucket.org/quark-zju/hg-draft  -r 058074cf24ce
>>> help: hide command line options marked as "advanced"
>>>
>>> Previously, we have keywords like "(DEPRECATED)" and "(EXPERIMENTAL)" to
>>> hide command line options in non-verbose help output.
>>>
>>> However, sometimes an option is neither deprecated nor experimental. It's
>>> well-tested and working, but just not designed to average users. This patch
>>> adds a keyword "(ADVANCED)" to fit in such use cases.
>>>
>>> Thanks rom1dep for the suggestion of the word "advanced".
>>
>> Do we have any candidate for this in core ?
>
> It should be better than "(VERBOSE)".

I'm very confused by this reply. My question is

"Do we currently have any flag in core that could benefit from this new 
feature?"

>
>> We probably need to hint the fact we have more to show here. Having
>> verbose section display a note about it, we should have the same here.
>
> It currently displays the same way as other keywords:
> "(some details hidden, use --verbose to show complete help)".
> That's included in the .t change below.
>
> Do you mean a different hint text? I don't think it's that useful.

Ha, I someone missed that line in the test. Sorry. I don't think we need 
anything other hint.
Jun Wu - Nov. 2, 2016, 2:10 a.m.
Excerpts from Pierre-Yves David's message of 2016-11-02 02:52:36 +0100:
> 
> On 11/02/2016 12:49 AM, Jun Wu wrote:
> > Excerpts from Pierre-Yves David's message of 2016-11-02 00:41:03 +0100:
> >>
> >> On 11/01/2016 04:08 PM, Jun Wu wrote:
> >>> # HG changeset patch
> >>> # User Jun Wu <quark@fb.com>
> >>> # Date 1478011845 0
> >>> #      Tue Nov 01 14:50:45 2016 +0000
> >>> # Node ID 058074cf24ce30ee0bc6d6a4d91fbe35631f8e8e
> >>> # Parent  264f00b3e5f045ac5b58d79e2a3976585f4e7739
> >>> # Available At https://bitbucket.org/quark-zju/hg-draft 
> >>> #              hg pull https://bitbucket.org/quark-zju/hg-draft   -r 058074cf24ce
> >>> help: hide command line options marked as "advanced"
> >>>
> >>> Previously, we have keywords like "(DEPRECATED)" and "(EXPERIMENTAL)" to
> >>> hide command line options in non-verbose help output.
> >>>
> >>> However, sometimes an option is neither deprecated nor experimental. It's
> >>> well-tested and working, but just not designed to average users. This patch
> >>> adds a keyword "(ADVANCED)" to fit in such use cases.
> >>>
> >>> Thanks rom1dep for the suggestion of the word "advanced".
> >>
> >> Do we have any candidate for this in core ?
                    ^^^^^^^^^
                    It can be "other keyword candidates".

> >
> > It should be better than "(VERBOSE)".
> 
> I'm very confused by this reply. My question is
> 
> "Do we currently have any flag in core that could benefit from this new 
> feature?"

I couldn't find candidates easily. For evolve, I think "graft -o/-O" may
qualify.

> >
> >> We probably need to hint the fact we have more to show here. Having
> >> verbose section display a note about it, we should have the same here.
> >
> > It currently displays the same way as other keywords:
> > "(some details hidden, use --verbose to show complete help)".
> > That's included in the .t change below.
> >
> > Do you mean a different hint text? I don't think it's that useful.
> 
> Ha, I someone missed that line in the test. Sorry. I don't think we need 
> anything other hint.
>
Pierre-Yves David - Nov. 19, 2016, 10:05 a.m.
On 11/02/2016 03:10 AM, Jun Wu wrote:
> Excerpts from Pierre-Yves David's message of 2016-11-02 02:52:36 +0100:
>>
>> On 11/02/2016 12:49 AM, Jun Wu wrote:
>>> Excerpts from Pierre-Yves David's message of 2016-11-02 00:41:03 +0100:
>>>>
>>>> On 11/01/2016 04:08 PM, Jun Wu wrote:
>>>>> # HG changeset patch
>>>>> # User Jun Wu <quark@fb.com>
>>>>> # Date 1478011845 0
>>>>> #      Tue Nov 01 14:50:45 2016 +0000
>>>>> # Node ID 058074cf24ce30ee0bc6d6a4d91fbe35631f8e8e
>>>>> # Parent  264f00b3e5f045ac5b58d79e2a3976585f4e7739
>>>>> # Available At https://bitbucket.org/quark-zju/hg-draft
>>>>> #              hg pull https://bitbucket.org/quark-zju/hg-draft   -r 058074cf24ce
>>>>> help: hide command line options marked as "advanced"
>>>>>
>>>>> Previously, we have keywords like "(DEPRECATED)" and "(EXPERIMENTAL)" to
>>>>> hide command line options in non-verbose help output.
>>>>>
>>>>> However, sometimes an option is neither deprecated nor experimental. It's
>>>>> well-tested and working, but just not designed to average users. This patch
>>>>> adds a keyword "(ADVANCED)" to fit in such use cases.
>>>>>
>>>>> Thanks rom1dep for the suggestion of the word "advanced".
>>>>
>>>> Do we have any candidate for this in core ?
>                     ^^^^^^^^^
>                     It can be "other keyword candidates".
>
>>>
>>> It should be better than "(VERBOSE)".
>>
>> I'm very confused by this reply. My question is
>>
>> "Do we currently have any flag in core that could benefit from this new
>> feature?"
>
> I couldn't find candidates easily. For evolve, I think "graft -o/-O" may
> qualify.

I'm more looking for user in core.

hg serve have some flag only used by other script, they seems good 
candidate. This could make good initial user

     --stdio                     for remote clients
     --cmdserver MODE            for remote clients

The --ssh related flag for clone and push/pull are probably good 
candidate too (but it is less clear)

Can you send a V3 flag --stdio and --cmdserver as advanced, I would most 
probably take that.

Cheers,
Jun Wu - Nov. 19, 2016, 2:36 p.m.
Excerpts from Pierre-Yves David's message of 2016-11-19 11:05:25 +0100:
> 
> On 11/02/2016 03:10 AM, Jun Wu wrote:
> > Excerpts from Pierre-Yves David's message of 2016-11-02 02:52:36 +0100:
> >>
> >> On 11/02/2016 12:49 AM, Jun Wu wrote:
> >>> Excerpts from Pierre-Yves David's message of 2016-11-02 00:41:03 +0100:
> >>>>
> >>>> On 11/01/2016 04:08 PM, Jun Wu wrote:
> >>>>> # HG changeset patch
> >>>>> # User Jun Wu <quark@fb.com>
> >>>>> # Date 1478011845 0
> >>>>> #      Tue Nov 01 14:50:45 2016 +0000
> >>>>> # Node ID 058074cf24ce30ee0bc6d6a4d91fbe35631f8e8e
> >>>>> # Parent  264f00b3e5f045ac5b58d79e2a3976585f4e7739
> >>>>> # Available At https://bitbucket.org/quark-zju/hg-draft 
> >>>>> #              hg pull https://bitbucket.org/quark-zju/hg-draft    -r 058074cf24ce
> >>>>> help: hide command line options marked as "advanced"
> >>>>>
> >>>>> Previously, we have keywords like "(DEPRECATED)" and "(EXPERIMENTAL)" to
> >>>>> hide command line options in non-verbose help output.
> >>>>>
> >>>>> However, sometimes an option is neither deprecated nor experimental. It's
> >>>>> well-tested and working, but just not designed to average users. This patch
> >>>>> adds a keyword "(ADVANCED)" to fit in such use cases.
> >>>>>
> >>>>> Thanks rom1dep for the suggestion of the word "advanced".
> >>>>
> >>>> Do we have any candidate for this in core ?
> >                     ^^^^^^^^^
> >                     It can be "other keyword candidates".
> >
> >>>
> >>> It should be better than "(VERBOSE)".
> >>
> >> I'm very confused by this reply. My question is
> >>
> >> "Do we currently have any flag in core that could benefit from this new
> >> feature?"
> >
> > I couldn't find candidates easily. For evolve, I think "graft -o/-O" may
> > qualify.
> 
> I'm more looking for user in core.
> 
> hg serve have some flag only used by other script, they seems good 
> candidate. This could make good initial user
> 
>      --stdio                     for remote clients
>      --cmdserver MODE            for remote clients
> 
> The --ssh related flag for clone and push/pull are probably good 
> candidate too (but it is less clear)
> 
> Can you send a V3 flag --stdio and --cmdserver as advanced, I would most 
> probably take that.

Do you mean folding the flag changes into this patch? I think that should be
a separate patch (and you agreed on this on IRC).

I'm not sure what needs to be changed for this patch. If I send a V3 of two
patches where the second is the flag change as you described, the first
patch in V3 would be identical to the current one. I'm not sure why is that
better than queuing this + sending just the flag change patch.

> 
> Cheers,
>
Pierre-Yves David - Nov. 25, 2016, 8:47 a.m.
On 11/19/2016 03:36 PM, Jun Wu wrote:
> Excerpts from Pierre-Yves David's message of 2016-11-19 11:05:25 +0100:
>>
>> On 11/02/2016 03:10 AM, Jun Wu wrote:
>>> Excerpts from Pierre-Yves David's message of 2016-11-02 02:52:36 +0100:
>>>>
>>>> On 11/02/2016 12:49 AM, Jun Wu wrote:
>>>>> Excerpts from Pierre-Yves David's message of 2016-11-02 00:41:03 +0100:
>>>>>>
>>>>>> On 11/01/2016 04:08 PM, Jun Wu wrote:
>>>>>>> # HG changeset patch
>>>>>>> # User Jun Wu <quark@fb.com>
>>>>>>> # Date 1478011845 0
>>>>>>> #      Tue Nov 01 14:50:45 2016 +0000
>>>>>>> # Node ID 058074cf24ce30ee0bc6d6a4d91fbe35631f8e8e
>>>>>>> # Parent  264f00b3e5f045ac5b58d79e2a3976585f4e7739
>>>>>>> # Available At https://bitbucket.org/quark-zju/hg-draft
>>>>>>> #              hg pull https://bitbucket.org/quark-zju/hg-draft    -r 058074cf24ce
>>>>>>> help: hide command line options marked as "advanced"
>>>>>>>
>>>>>>> Previously, we have keywords like "(DEPRECATED)" and "(EXPERIMENTAL)" to
>>>>>>> hide command line options in non-verbose help output.
>>>>>>>
>>>>>>> However, sometimes an option is neither deprecated nor experimental. It's
>>>>>>> well-tested and working, but just not designed to average users. This patch
>>>>>>> adds a keyword "(ADVANCED)" to fit in such use cases.
>>>>>>>
>>>>>>> Thanks rom1dep for the suggestion of the word "advanced".
>>>>>>
>>>>>> Do we have any candidate for this in core ?
>>>                     ^^^^^^^^^
>>>                     It can be "other keyword candidates".
>>>
>>>>>
>>>>> It should be better than "(VERBOSE)".
>>>>
>>>> I'm very confused by this reply. My question is
>>>>
>>>> "Do we currently have any flag in core that could benefit from this new
>>>> feature?"
>>>
>>> I couldn't find candidates easily. For evolve, I think "graft -o/-O" may
>>> qualify.
>>
>> I'm more looking for user in core.
>>
>> hg serve have some flag only used by other script, they seems good
>> candidate. This could make good initial user
>>
>>      --stdio                     for remote clients
>>      --cmdserver MODE            for remote clients
>>
>> The --ssh related flag for clone and push/pull are probably good
>> candidate too (but it is less clear)
>>
>> Can you send a V3 flag --stdio and --cmdserver as advanced, I would most
>> probably take that.
>
> Do you mean folding the flag changes into this patch? I think that should be
> a separate patch (and you agreed on this on IRC).
>
> I'm not sure what needs to be changed for this patch. If I send a V3 of two
> patches where the second is the flag change as you described, the first
> patch in V3 would be identical to the current one. I'm not sure why is that
> better than queuing this + sending just the flag change patch.

That patch seems fine but got dropped from patchwork a while back. It 
seem simpler for you to resend it alongside the other if you don't mind.

Cheers,

Patch

diff --git a/mercurial/help.py b/mercurial/help.py
--- a/mercurial/help.py
+++ b/mercurial/help.py
@@ -34,12 +34,15 @@  from .hgweb import (
 )
 
-_exclkeywords = [
+_exclkeywords = set([
+    "(ADVANCED)",
     "(DEPRECATED)",
     "(EXPERIMENTAL)",
+    # i18n: "(ADVANCED)" is a keyword, must be translated consistently
+    _("(ADVANCED)"),
     # i18n: "(DEPRECATED)" is a keyword, must be translated consistently
     _("(DEPRECATED)"),
     # i18n: "(EXPERIMENTAL)" is a keyword, must be translated consistently
     _("(EXPERIMENTAL)"),
-    ]
+    ])
 
 def listexts(header, exts, indent=1, showdeprecated=False):
diff --git a/tests/test-help.t b/tests/test-help.t
--- a/tests/test-help.t
+++ b/tests/test-help.t
@@ -684,4 +684,5 @@  this is a section and erroring out weird
   >     'hg nohelp',
   >     norepo=True)
+  > @command('debugoptADV', [('', 'aopt', None, 'option is (ADVANCED)')])
   > @command('debugoptDEP', [('', 'dopt', None, 'option is (DEPRECATED)')])
   > @command('debugoptEXP', [('', 'eopt', None, 'option is (EXPERIMENTAL)')])
@@ -897,4 +898,5 @@  Test list of internal help commands
    debugobsolete
                  create arbitrary obsolete marker
+   debugoptADV   (no help text available)
    debugoptDEP   (no help text available)
    debugoptEXP   (no help text available)
@@ -1108,5 +1110,13 @@  Test list of commands with command with 
 
 
-test deprecated and experimental options are hidden in command help
+test advanced, deprecated and experimental options are hidden in command help
+  $ hg help debugoptADV
+  hg debugoptADV
+  
+  (no help text available)
+  
+  options:
+  
+  (some details hidden, use --verbose to show complete help)
   $ hg help debugoptDEP
   hg debugoptDEP
@@ -1127,5 +1137,7 @@  test deprecated and experimental options
   (some details hidden, use --verbose to show complete help)
 
-test deprecated and experimental options is shown with -v
+test advanced, deprecated and experimental options are shown with -v
+  $ hg help -v debugoptADV | grep aopt
+    --aopt option is (ADVANCED)
   $ hg help -v debugoptDEP | grep dopt
     --dopt option is (DEPRECATED)