Patchwork [2,of,4,V2] progress: move config help into core config help

login
register
mail settings
Submitter Pierre-Yves David
Date June 10, 2015, 7:02 p.m.
Message ID <00e625c98575d0e6c93b.1433962963@marginatus.alto.octopoid.net>
Download mbox | patch
Permalink /patch/9588/
State Superseded
Headers show

Comments

Pierre-Yves David - June 10, 2015, 7:02 p.m.
# HG changeset patch
# User Pierre-Yves David <pierre-yves.david@fb.com>
# Date 1433962615 25200
#      Wed Jun 10 11:56:55 2015 -0700
# Node ID 00e625c98575d0e6c93b57faaf741093285fd4b5
# Parent  f81552058c8b90a5caca16aebe7fc2cb6de2d837
progress: move config help into core config help

This is core feature now.
Gilles Moris - June 11, 2015, 6:01 a.m.
Le 10/06/2015 21:02, Pierre-Yves David a écrit :
> # HG changeset patch
> # User Pierre-Yves David <pierre-yves.david@fb.com>
> # Date 1433962615 25200
> #      Wed Jun 10 11:56:55 2015 -0700
> # Node ID 00e625c98575d0e6c93b57faaf741093285fd4b5
> # Parent  f81552058c8b90a5caca16aebe7fc2cb6de2d837
> progress: move config help into core config help
>
> This is core feature now.
>
> diff --git a/hgext/progress.py b/hgext/progress.py
> --- a/hgext/progress.py
> +++ b/hgext/progress.py
> @@ -9,32 +9,10 @@
>   
>   This extension uses the progress information logged by hg commands
>   to draw progress bars that are as informative as possible. Some progress
>   bars only offer indeterminate information, while others have a definite
>   end point.
> -
> -The following settings are available::
> -
> -  [progress]
> -  delay = 3 # number of seconds (float) before showing the progress bar
> -  changedelay = 1 # changedelay: minimum delay before showing a new topic.
> -                  # If set to less than 3 * refresh, that value will
> -                  # be used instead.
> -  refresh = 0.1 # time in seconds between refreshes of the progress bar
> -  format = topic bar number estimate # format of the progress bar
> -  width = <none> # if set, the maximum width of the progress information
> -                 # (that is, min(width, term width) will be used)
> -  clear-complete = True # clear the progress bar after it's done
> -  disable = False # if true, don't show a progress bar
> -  assume-tty = False # if true, ALWAYS show a progress bar, unless
> -                     # disable is given
> -
> -Valid entries for the format field are topic, bar, number, unit,
> -estimate, speed, and item. item defaults to the last 20 characters of
> -the item, but this can be changed by adding either ``-<num>`` which
> -would take the last num characters, or ``+<num>`` for the first num
> -characters.
>   """
>   
>   def uisetup(ui):
>       if ui.config('progress', 'disable', None) is None:
>           ui.setconfig('progress', 'disable', 'False', 'hgext-progress')
> diff --git a/mercurial/help/config.txt b/mercurial/help/config.txt
> --- a/mercurial/help/config.txt
> +++ b/mercurial/help/config.txt
> @@ -1212,10 +1212,48 @@ profiling is done using lsprof.
>       Show at most this number of lines of drill-down info after each main entry.
>       This can help explain the difference between Total and Inline.
>       Specific to the ``ls`` instrumenting profiler.
>       Default: 5.
>   
> +``progress``
> +------------
> +
> +Mercurial hg commands can draw progress bars that are as informative as
> +possible. Some progress bars only offer indeterminate information, while others
> +have a definite end point.

We lost the default values for all those config knob.
I think we should keep them.
> +
> +``delay``
> +    Number of seconds (float) before showing the progress bar.
> +
> +``changedelay``
> +    Minimum delay before showing a new topic. When set to less than 3 * refresh,
> +    that value will be used instead.
> +
> +``refresh``
> +    Time in seconds between refreshes of the progress bar.
> +
> +``format``
> +    Topic bar number estimate # format of the progress bar.
Do you want to keep the "# format of the progress bar"? Seems a comment 
of the previous example.
Or may be in parenthesis, or introduced by a word rather than "#".
> +
> +    Valid entries for the format field are topic, bar, number, unit, estimate,
> +    speed, and item. item defaults to the last 20 characters of the item, but
May be "topic", "bar", "number", ... should be quoted to make it clear 
they are expected keywords.
Or use some markup.

Regards.
Gilles.
> +    this can be changed by adding either ``-<num>`` which would take the last
> +    num characters, or ``+<num>`` for the first num characters.
> +
> +``width``
> +    If set, the maximum width of the progress information (that is, min(width,
> +    term width) will be used)
> +
> +``clear-complete``
> +    clear the progress bar after it's done (default to True)
> +
> +``disable``
> +    If true, don't show a progress bar
> +
> +``assume-tty``
> +    If true, ALWAYS show a progress bar, unless disable is given
> +
>   ``revsetalias``
>   ---------------
>   
>   Alias definitions for revsets. See :hg:`help revsets` for details.
>   
> _______________________________________________
> Mercurial-devel mailing list
> Mercurial-devel@selenic.com
> https://selenic.com/mailman/listinfo/mercurial-devel
Pierre-Yves David - June 11, 2015, 7:23 a.m.
On 06/10/2015 11:01 PM, Gilles Moris wrote:
> Le 10/06/2015 21:02, Pierre-Yves David a écrit :
>> # HG changeset patch
>> # User Pierre-Yves David <pierre-yves.david@fb.com>
>> # Date 1433962615 25200
>> #      Wed Jun 10 11:56:55 2015 -0700
>> # Node ID 00e625c98575d0e6c93b57faaf741093285fd4b5
>> # Parent  f81552058c8b90a5caca16aebe7fc2cb6de2d837
>> progress: move config help into core config help
>>
>> This is core feature now.
>>
>> diff --git a/hgext/progress.py b/hgext/progress.py
>> --- a/hgext/progress.py
>> +++ b/hgext/progress.py
>> @@ -9,32 +9,10 @@
>>   This extension uses the progress information logged by hg commands
>>   to draw progress bars that are as informative as possible. Some
>> progress
>>   bars only offer indeterminate information, while others have a definite
>>   end point.
>> -
>> -The following settings are available::
>> -
>> -  [progress]
>> -  delay = 3 # number of seconds (float) before showing the progress bar
>> -  changedelay = 1 # changedelay: minimum delay before showing a new
>> topic.
>> -                  # If set to less than 3 * refresh, that value will
>> -                  # be used instead.
>> -  refresh = 0.1 # time in seconds between refreshes of the progress bar
>> -  format = topic bar number estimate # format of the progress bar
>> -  width = <none> # if set, the maximum width of the progress information
>> -                 # (that is, min(width, term width) will be used)
>> -  clear-complete = True # clear the progress bar after it's done
>> -  disable = False # if true, don't show a progress bar
>> -  assume-tty = False # if true, ALWAYS show a progress bar, unless
>> -                     # disable is given
>> -
>> -Valid entries for the format field are topic, bar, number, unit,
>> -estimate, speed, and item. item defaults to the last 20 characters of
>> -the item, but this can be changed by adding either ``-<num>`` which
>> -would take the last num characters, or ``+<num>`` for the first num
>> -characters.
>>   """
>>   def uisetup(ui):
>>       if ui.config('progress', 'disable', None) is None:
>>           ui.setconfig('progress', 'disable', 'False', 'hgext-progress')
>> diff --git a/mercurial/help/config.txt b/mercurial/help/config.txt
>> --- a/mercurial/help/config.txt
>> +++ b/mercurial/help/config.txt
>> @@ -1212,10 +1212,48 @@ profiling is done using lsprof.
>>       Show at most this number of lines of drill-down info after each
>> main entry.
>>       This can help explain the difference between Total and Inline.
>>       Specific to the ``ls`` instrumenting profiler.
>>       Default: 5.
>> +``progress``
>> +------------
>> +
>> +Mercurial hg commands can draw progress bars that are as informative as
>> +possible. Some progress bars only offer indeterminate information,
>> while others
>> +have a definite end point.
>
> We lost the default values for all those config knob.
> I think we should keep them.

Hum true.

That's probably a maintenance nightmare to put them in the doc but 
having them displayed somewhere is important, so I guess that the doc is 
the best place.


>> +
>> +``delay``
>> +    Number of seconds (float) before showing the progress bar.
>> +
>> +``changedelay``
>> +    Minimum delay before showing a new topic. When set to less than 3
>> * refresh,
>> +    that value will be used instead.
>> +
>> +``refresh``
>> +    Time in seconds between refreshes of the progress bar.
>> +
>> +``format``
>> +    Topic bar number estimate # format of the progress bar.
> Do you want to keep the "# format of the progress bar"? Seems a comment
> of the previous example.
> Or may be in parenthesis, or introduced by a word rather than "#".
>> +
>> +    Valid entries for the format field are topic, bar, number, unit,
>> estimate,
>> +    speed, and item. item defaults to the last 20 characters of the
>> item, but
> May be "topic", "bar", "number", ... should be quoted to make it clear
> they are expected keywords.
> Or use some markup.

You're right, this whould probably be a "valid entry: "topic", "bar", 
"number", "estimate".

I'll send a V3.
Gregory Szorc - June 13, 2015, 5:05 p.m.
On Thu, Jun 11, 2015 at 12:23 AM, Pierre-Yves David <
pierre-yves.david@ens-lyon.org> wrote:

>
>
> On 06/10/2015 11:01 PM, Gilles Moris wrote:
>
>> Le 10/06/2015 21:02, Pierre-Yves David a écrit :
>>
>>> # HG changeset patch
>>> # User Pierre-Yves David <pierre-yves.david@fb.com>
>>> # Date 1433962615 25200
>>> #      Wed Jun 10 11:56:55 2015 -0700
>>> # Node ID 00e625c98575d0e6c93b57faaf741093285fd4b5
>>> # Parent  f81552058c8b90a5caca16aebe7fc2cb6de2d837
>>> progress: move config help into core config help
>>>
>>> This is core feature now.
>>>
>>> diff --git a/hgext/progress.py b/hgext/progress.py
>>> --- a/hgext/progress.py
>>> +++ b/hgext/progress.py
>>> @@ -9,32 +9,10 @@
>>>   This extension uses the progress information logged by hg commands
>>>   to draw progress bars that are as informative as possible. Some
>>> progress
>>>   bars only offer indeterminate information, while others have a definite
>>>   end point.
>>> -
>>> -The following settings are available::
>>> -
>>> -  [progress]
>>> -  delay = 3 # number of seconds (float) before showing the progress bar
>>> -  changedelay = 1 # changedelay: minimum delay before showing a new
>>> topic.
>>> -                  # If set to less than 3 * refresh, that value will
>>> -                  # be used instead.
>>> -  refresh = 0.1 # time in seconds between refreshes of the progress bar
>>> -  format = topic bar number estimate # format of the progress bar
>>> -  width = <none> # if set, the maximum width of the progress information
>>> -                 # (that is, min(width, term width) will be used)
>>> -  clear-complete = True # clear the progress bar after it's done
>>> -  disable = False # if true, don't show a progress bar
>>> -  assume-tty = False # if true, ALWAYS show a progress bar, unless
>>> -                     # disable is given
>>> -
>>> -Valid entries for the format field are topic, bar, number, unit,
>>> -estimate, speed, and item. item defaults to the last 20 characters of
>>> -the item, but this can be changed by adding either ``-<num>`` which
>>> -would take the last num characters, or ``+<num>`` for the first num
>>> -characters.
>>>   """
>>>   def uisetup(ui):
>>>       if ui.config('progress', 'disable', None) is None:
>>>           ui.setconfig('progress', 'disable', 'False', 'hgext-progress')
>>> diff --git a/mercurial/help/config.txt b/mercurial/help/config.txt
>>> --- a/mercurial/help/config.txt
>>> +++ b/mercurial/help/config.txt
>>> @@ -1212,10 +1212,48 @@ profiling is done using lsprof.
>>>       Show at most this number of lines of drill-down info after each
>>> main entry.
>>>       This can help explain the difference between Total and Inline.
>>>       Specific to the ``ls`` instrumenting profiler.
>>>       Default: 5.
>>> +``progress``
>>> +------------
>>> +
>>> +Mercurial hg commands can draw progress bars that are as informative as
>>> +possible. Some progress bars only offer indeterminate information,
>>> while others
>>> +have a definite end point.
>>>
>>
>> We lost the default values for all those config knob.
>> I think we should keep them.
>>
>
> Hum true.
>
> That's probably a maintenance nightmare to put them in the doc but having
> them displayed somewhere is important, so I guess that the doc is the best
> place.


This touches on existing problems with config option documentation:

* Config options for extensions don't get documented in `hg help config`
(only in the help for an extension)
* It is easy to add config options without documenting them

I'm generally interested in making docs/help suck less. One idea I had was
to declare config options using decorators/functions. e.g.

@config('histedit', 'defaultrev')
def defaultrev():
    """The default revision to use for ``hg histedit``.

    ``hg histedit`` requires a revision argument. When this option is
defined,
    its value will be used when no option is provided on the command
invocation.
    """

"Strong typing" of config options could open the door to some interesting
possibilities:

* Having config option functions validate seen values. If there are
multiple use sites, we only have to write the validation code once instead
of potentially at every use site.
* Error if an undocumented config option is looked up (probably from tests
only - at least initially - but better than nothing)
* Removing typing from lookups. If config options declare their types,
ui.config() can do the right thing and callers don't need to be bothered
with configbool(), configint(), etc.

I concede that decorators and functions may seem a bit heavyweight for
declaring options. And, loading all the Python modules just to display "hg
help config" seems like a step in the wrong direction. I'm open to other
ideas for solving the problems outlined above.

Patch

diff --git a/hgext/progress.py b/hgext/progress.py
--- a/hgext/progress.py
+++ b/hgext/progress.py
@@ -9,32 +9,10 @@ 
 
 This extension uses the progress information logged by hg commands
 to draw progress bars that are as informative as possible. Some progress
 bars only offer indeterminate information, while others have a definite
 end point.
-
-The following settings are available::
-
-  [progress]
-  delay = 3 # number of seconds (float) before showing the progress bar
-  changedelay = 1 # changedelay: minimum delay before showing a new topic.
-                  # If set to less than 3 * refresh, that value will
-                  # be used instead.
-  refresh = 0.1 # time in seconds between refreshes of the progress bar
-  format = topic bar number estimate # format of the progress bar
-  width = <none> # if set, the maximum width of the progress information
-                 # (that is, min(width, term width) will be used)
-  clear-complete = True # clear the progress bar after it's done
-  disable = False # if true, don't show a progress bar
-  assume-tty = False # if true, ALWAYS show a progress bar, unless
-                     # disable is given
-
-Valid entries for the format field are topic, bar, number, unit,
-estimate, speed, and item. item defaults to the last 20 characters of
-the item, but this can be changed by adding either ``-<num>`` which
-would take the last num characters, or ``+<num>`` for the first num
-characters.
 """
 
 def uisetup(ui):
     if ui.config('progress', 'disable', None) is None:
         ui.setconfig('progress', 'disable', 'False', 'hgext-progress')
diff --git a/mercurial/help/config.txt b/mercurial/help/config.txt
--- a/mercurial/help/config.txt
+++ b/mercurial/help/config.txt
@@ -1212,10 +1212,48 @@  profiling is done using lsprof.
     Show at most this number of lines of drill-down info after each main entry.
     This can help explain the difference between Total and Inline.
     Specific to the ``ls`` instrumenting profiler.
     Default: 5.
 
+``progress``
+------------
+
+Mercurial hg commands can draw progress bars that are as informative as
+possible. Some progress bars only offer indeterminate information, while others
+have a definite end point.
+
+``delay``
+    Number of seconds (float) before showing the progress bar.
+
+``changedelay``
+    Minimum delay before showing a new topic. When set to less than 3 * refresh,
+    that value will be used instead.
+
+``refresh``
+    Time in seconds between refreshes of the progress bar.
+
+``format``
+    Topic bar number estimate # format of the progress bar.
+
+    Valid entries for the format field are topic, bar, number, unit, estimate,
+    speed, and item. item defaults to the last 20 characters of the item, but
+    this can be changed by adding either ``-<num>`` which would take the last
+    num characters, or ``+<num>`` for the first num characters.
+
+``width``
+    If set, the maximum width of the progress information (that is, min(width,
+    term width) will be used)
+
+``clear-complete``
+    clear the progress bar after it's done (default to True)
+
+``disable``
+    If true, don't show a progress bar
+
+``assume-tty``
+    If true, ALWAYS show a progress bar, unless disable is given
+
 ``revsetalias``
 ---------------
 
 Alias definitions for revsets. See :hg:`help revsets` for details.