Patchwork [v5] help: mark boolean flags with [no-] to explain that they can be negated (RFC)

login
register
mail settings
Submitter Augie Fackler
Date Sept. 27, 2016, 9:55 p.m.
Message ID <7f6af551cbc5394441f6.1475013357@augie-macbookair2.roam.corp.google.com>
Download mbox | patch
Permalink /patch/16795/
State Superseded
Headers show

Comments

Augie Fackler - Sept. 27, 2016, 9:55 p.m.
# HG changeset patch
# User Augie Fackler <augie@google.com>
# Date 1473821892 14400
#      Tue Sep 13 22:58:12 2016 -0400
# Node ID 7f6af551cbc5394441f62383e5ced5084f59bff5
# Parent  e83f89d3b1f733d0ee5f23f6a2293279a17fbbfb
help: mark boolean flags with [no-] to explain that they can be negated (RFC)

That is, help gets tweaked thus:

  global options ([+] can be repeated):
   -v --[no-]verbose      enable additional output


Still an RFC because it's still unclear what we should do. Other
proposals have included:

  global options ([+] can be repeated, options marked [?] are boolean flags):
   -v --verbose[?]        enable additional output

and

  global options ([+] can be repeated, options marked [^] are boolean flags):
   -v --verbose[^]        enable additional output

which avoid the visual noise of the current approach in this change is
unfortunate, it matches the format I'm used to seeing in man pages and
similar documentation venues.
Pierre-Yves David - Sept. 28, 2016, 12:25 p.m.
On 09/27/2016 11:55 PM, Augie Fackler wrote:
> # HG changeset patch
> # User Augie Fackler <augie@google.com>
> # Date 1473821892 14400
> #      Tue Sep 13 22:58:12 2016 -0400
> # Node ID 7f6af551cbc5394441f62383e5ced5084f59bff5
> # Parent  e83f89d3b1f733d0ee5f23f6a2293279a17fbbfb
> help: mark boolean flags with [no-] to explain that they can be negated (RFC)
>
> That is, help gets tweaked thus:
>
>   global options ([+] can be repeated):
>    -v --[no-]verbose      enable additional output
>
>
> Still an RFC because it's still unclear what we should do. Other
> proposals have included:
>
>   global options ([+] can be repeated, options marked [?] are boolean flags):
>    -v --verbose[?]        enable additional output
>
> and
>
>   global options ([+] can be repeated, options marked [^] are boolean flags):
>    -v --verbose[^]        enable additional output
>
> which avoid the visual noise of the current approach in this change is
> unfortunate, it matches the format I'm used to seeing in man pages and
> similar documentation venues.

I'm confused about this sentence. It seems like some part is missing. 
What is unfortunate? What version is matching the format we are use to 
seeing in man pages?

Cheers,
Augie Fackler - Sept. 28, 2016, 1:32 p.m.
> On Sep 28, 2016, at 08:25, Pierre-Yves David <pierre-yves.david@ens-lyon.org> wrote:
> 
>> which avoid the visual noise of the current approach in this change is
>> unfortunate, it matches the format I'm used to seeing in man pages and
>> similar documentation venues.
> 
> I'm confused about this sentence. It seems like some part is missing. What is unfortunate? What version is matching the format we are use to seeing in man pages?


The current version -> the version in v5

has unfortunate visual clutter, but also matches what I'm used to seeing in man pages.

I'll grant you it's an unusual construction though. Perhaps


> which avoid the unfortunate visual noise in this patch. In this version's favor, it's consistent with what I'm used to seeing in man pages and similar documentation venues.

is clearer?
Pierre-Yves David - Sept. 28, 2016, 1:35 p.m.
On 09/28/2016 03:32 PM, Augie Fackler wrote:
>
>> On Sep 28, 2016, at 08:25, Pierre-Yves David
>> <pierre-yves.david@ens-lyon.org
>> <mailto:pierre-yves.david@ens-lyon.org>> wrote:
>>
>>> which avoid the visual noise of the current approach in this change is
>>> unfortunate, it matches the format I'm used to seeing in man pages and
>>> similar documentation venues.
>>
>> I'm confused about this sentence. It seems like some part is missing.
>> What is unfortunate? What version is matching the format we are use to
>> seeing in man pages?
>
> The current version -> the version in v5
>
> has unfortunate visual clutter, but also matches what I'm used to seeing
> in man pages.
>
> I'll grant you it's an unusual construction though. Perhaps
>
>> which avoid the unfortunate visual noise in this patch. In this
>> version's favor, it's consistent with what I'm used to seeing in man
>> pages and similar documentation venues.
>
> is clearer?

Yep. thank you very much
Yuya Nishihara - Sept. 29, 2016, 2:33 p.m.
On Wed, 28 Sep 2016 17:24:59 -0500, Kevin Bullock wrote:
> > On Sep 28, 2016, at 12:07, Augie Fackler <raf@durin42.com> wrote:
> > Should I mail a v6? How do people feel about this particular patch, commit message aside?
> 
> I'd say it's the cleanest of the options presented thus far. I'm in favor.

I like this, too.

> +            else:
> +                if ('no-' + longopt) not in alllong:
> +                    lo = '--[no-]' + lo[2:]
> +            multioccur = True

'multioccur = True' looks like a remainder from the previous round.

Patch

diff --git a/mercurial/help.py b/mercurial/help.py
--- a/mercurial/help.py
+++ b/mercurial/help.py
@@ -20,6 +20,7 @@  from . import (
     encoding,
     error,
     extensions,
+    fancyopts,
     filemerge,
     fileset,
     minirst,
@@ -65,6 +66,7 @@  def extshelp(ui):
 def optrst(header, options, verbose):
     data = []
     multioccur = False
+    alllong = set(o[1] for o in options)
     for option in options:
         if len(option) == 5:
             shortopt, longopt, default, desc, optlabel = option
@@ -87,6 +89,17 @@  def optrst(header, options, verbose):
             multioccur = True
         elif (default is not None) and not isinstance(default, bool):
             lo += " %s" % optlabel
+        elif longopt not in fancyopts.nevernegate:
+            if longopt.startswith('no-'):
+                # This odd if statement guards against showing
+                # --no-commit and --commit on backout (as a practical
+                # example) as --[no-]commit in help.
+                if (longopt[3:]) not in alllong:
+                    lo = '--[no-]' + lo[5:]
+            else:
+                if ('no-' + longopt) not in alllong:
+                    lo = '--[no-]' + lo[2:]
+            multioccur = True
 
         data.append((so, lo, desc))
 
diff --git a/tests/test-help.t b/tests/test-help.t
--- a/tests/test-help.t
+++ b/tests/test-help.t
@@ -318,19 +318,19 @@  Test short command list with verbose opt
       --cwd DIR           change working directory
    -y --noninteractive    do not prompt, automatically pick the first choice for
                           all prompts
-   -q --quiet             suppress output
-   -v --verbose           enable additional output
+   -q --[no-]quiet        suppress output
+   -v --[no-]verbose      enable additional output
       --config CONFIG [+] set/override config option (use 'section.name=value')
-      --debug             enable debugging output
-      --debugger          start debugger
+      --[no-]debug        enable debugging output
+      --[no-]debugger     start debugger
       --encoding ENCODE   set the charset encoding (default: ascii)
       --encodingmode MODE set the charset encoding mode (default: strict)
-      --traceback         always print a traceback on exception
-      --time              time how long the command takes
-      --profile           print command execution profile
+      --[no-]traceback    always print a traceback on exception
+      --[no-]time         time how long the command takes
+      --[no-]profile      print command execution profile
       --version           output version information and exit
    -h --help              display help and exit
-      --hidden            consider hidden changesets
+      --[no-]hidden       consider hidden changesets
   
   (use 'hg help' for the full list of commands)
 
@@ -353,8 +353,8 @@  Test short command list with verbose opt
   
    -I --include PATTERN [+] include names matching the given patterns
    -X --exclude PATTERN [+] exclude names matching the given patterns
-   -S --subrepos            recurse into subrepositories
-   -n --dry-run             do not perform actions, just print output
+   -S --[no-]subrepos       recurse into subrepositories
+   -n --[no-]dry-run        do not perform actions, just print output
   
   (some details hidden, use --verbose to show complete help)
 
@@ -404,8 +404,8 @@  Verbose help for add
   
    -I --include PATTERN [+] include names matching the given patterns
    -X --exclude PATTERN [+] exclude names matching the given patterns
-   -S --subrepos            recurse into subrepositories
-   -n --dry-run             do not perform actions, just print output
+   -S --[no-]subrepos       recurse into subrepositories
+   -n --[no-]dry-run        do not perform actions, just print output
   
   global options ([+] can be repeated):
   
@@ -414,19 +414,19 @@  Verbose help for add
       --cwd DIR           change working directory
    -y --noninteractive    do not prompt, automatically pick the first choice for
                           all prompts
-   -q --quiet             suppress output
-   -v --verbose           enable additional output
+   -q --[no-]quiet        suppress output
+   -v --[no-]verbose      enable additional output
       --config CONFIG [+] set/override config option (use 'section.name=value')
-      --debug             enable debugging output
-      --debugger          start debugger
+      --[no-]debug        enable debugging output
+      --[no-]debugger     start debugger
       --encoding ENCODE   set the charset encoding (default: ascii)
       --encodingmode MODE set the charset encoding mode (default: strict)
-      --traceback         always print a traceback on exception
-      --time              time how long the command takes
-      --profile           print command execution profile
+      --[no-]traceback    always print a traceback on exception
+      --[no-]time         time how long the command takes
+      --[no-]profile      print command execution profile
       --version           output version information and exit
    -h --help              display help and exit
-      --hidden            consider hidden changesets
+      --[no-]hidden       consider hidden changesets
 
 Test the textwidth config option
 
@@ -464,8 +464,8 @@  Test help option with version option
   
    -I --include PATTERN [+] include names matching the given patterns
    -X --exclude PATTERN [+] exclude names matching the given patterns
-   -S --subrepos            recurse into subrepositories
-   -n --dry-run             do not perform actions, just print output
+   -S --[no-]subrepos       recurse into subrepositories
+   -n --[no-]dry-run        do not perform actions, just print output
   
   (use 'hg add -h' to show more help)
   [255]
@@ -534,23 +534,23 @@  Test command without options
   
   options ([+] can be repeated):
   
-   -r --rev REV [+]         revision
-   -c --change REV          change made by revision
-   -a --text                treat all files as text
-   -g --git                 use git extended diff format
-      --nodates             omit dates from diff headers
-      --noprefix            omit a/ and b/ prefixes from filenames
-   -p --show-function       show which function each change is in
-      --reverse             produce a diff that undoes the changes
-   -w --ignore-all-space    ignore white space when comparing lines
-   -b --ignore-space-change ignore changes in the amount of white space
-   -B --ignore-blank-lines  ignore changes whose lines are all blank
-   -U --unified NUM         number of lines of context to show
-      --stat                output diffstat-style summary of changes
-      --root DIR            produce diffs relative to subdirectory
-   -I --include PATTERN [+] include names matching the given patterns
-   -X --exclude PATTERN [+] exclude names matching the given patterns
-   -S --subrepos            recurse into subrepositories
+   -r --rev REV [+]              revision
+   -c --change REV               change made by revision
+   -a --[no-]text                treat all files as text
+   -g --[no-]git                 use git extended diff format
+      --[no-]nodates             omit dates from diff headers
+      --[no-]noprefix            omit a/ and b/ prefixes from filenames
+   -p --[no-]show-function       show which function each change is in
+      --[no-]reverse             produce a diff that undoes the changes
+   -w --[no-]ignore-all-space    ignore white space when comparing lines
+   -b --[no-]ignore-space-change ignore changes in the amount of white space
+   -B --[no-]ignore-blank-lines  ignore changes whose lines are all blank
+   -U --unified NUM              number of lines of context to show
+      --[no-]stat                output diffstat-style summary of changes
+      --root DIR                 produce diffs relative to subdirectory
+   -I --include PATTERN [+]      include names matching the given patterns
+   -X --exclude PATTERN [+]      exclude names matching the given patterns
+   -S --[no-]subrepos            recurse into subrepositories
   
   (some details hidden, use --verbose to show complete help)
 
@@ -596,22 +596,22 @@  Test command without options
   
   options ([+] can be repeated):
   
-   -A --all                 show status of all files
-   -m --modified            show only modified files
-   -a --added               show only added files
-   -r --removed             show only removed files
-   -d --deleted             show only deleted (but tracked) files
-   -c --clean               show only files without changes
-   -u --unknown             show only unknown (not tracked) files
-   -i --ignored             show only ignored files
-   -n --no-status           hide status prefix
-   -C --copies              show source of copied files
-   -0 --print0              end filenames with NUL, for use with xargs
+   -A --[no-]all            show status of all files
+   -m --[no-]modified       show only modified files
+   -a --[no-]added          show only added files
+   -r --[no-]removed        show only removed files
+   -d --[no-]deleted        show only deleted (but tracked) files
+   -c --[no-]clean          show only files without changes
+   -u --[no-]unknown        show only unknown (not tracked) files
+   -i --[no-]ignored        show only ignored files
+   -n --[no-]status         hide status prefix
+   -C --[no-]copies         show source of copied files
+   -0 --[no-]print0         end filenames with NUL, for use with xargs
       --rev REV [+]         show difference from revision
       --change REV          list the changed files of a revision
    -I --include PATTERN [+] include names matching the given patterns
    -X --exclude PATTERN [+] exclude names matching the given patterns
-   -S --subrepos            recurse into subrepositories
+   -S --[no-]subrepos       recurse into subrepositories
   
   (some details hidden, use --verbose to show complete help)
 
@@ -715,9 +715,9 @@  Test for aliases
   
   defined by: helpext
   
-  options:
-  
-    --remote check for push and pull
+  options ([+] can be repeated):
+  
+    --[no-]remote check for push and pull
   
   (some details hidden, use --verbose to show complete help)
 
@@ -739,11 +739,11 @@  Test command with no help text
   
   (no help text available)
   
-  options:
+  options ([+] can be repeated):
   
       --longdesc VALUE xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
                        xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx (default: 3)
-   -n --               normal desc
+   -n --[no-]          normal desc
       --newline VALUE  line1 line2
   
   (some details hidden, use --verbose to show complete help)
@@ -1128,9 +1128,9 @@  test deprecated and experimental options
 
 test deprecated and experimental options is shown with -v
   $ hg help -v debugoptDEP | grep dopt
-    --dopt option is (DEPRECATED)
+    --[no-]dopt option is (DEPRECATED)
   $ hg help -v debugoptEXP | grep eopt
-    --eopt option is (EXPERIMENTAL)
+    --[no-]eopt option is (EXPERIMENTAL)
 
 #if gettext
 test deprecated option is hidden with translation with untranslated description
@@ -2474,10 +2474,10 @@  Dish up an empty repo; serve it cold.
   <td>--exclude PATTERN [+]</td>
   <td>exclude names matching the given patterns</td></tr>
   <tr><td>-S</td>
-  <td>--subrepos</td>
+  <td>--[no-]subrepos</td>
   <td>recurse into subrepositories</td></tr>
   <tr><td>-n</td>
-  <td>--dry-run</td>
+  <td>--[no-]dry-run</td>
   <td>do not perform actions, just print output</td></tr>
   </table>
   <p>
@@ -2494,19 +2494,19 @@  Dish up an empty repo; serve it cold.
   <td>--noninteractive</td>
   <td>do not prompt, automatically pick the first choice for all prompts</td></tr>
   <tr><td>-q</td>
-  <td>--quiet</td>
+  <td>--[no-]quiet</td>
   <td>suppress output</td></tr>
   <tr><td>-v</td>
-  <td>--verbose</td>
+  <td>--[no-]verbose</td>
   <td>enable additional output</td></tr>
   <tr><td></td>
   <td>--config CONFIG [+]</td>
   <td>set/override config option (use 'section.name=value')</td></tr>
   <tr><td></td>
-  <td>--debug</td>
+  <td>--[no-]debug</td>
   <td>enable debugging output</td></tr>
   <tr><td></td>
-  <td>--debugger</td>
+  <td>--[no-]debugger</td>
   <td>start debugger</td></tr>
   <tr><td></td>
   <td>--encoding ENCODE</td>
@@ -2515,13 +2515,13 @@  Dish up an empty repo; serve it cold.
   <td>--encodingmode MODE</td>
   <td>set the charset encoding mode (default: strict)</td></tr>
   <tr><td></td>
-  <td>--traceback</td>
+  <td>--[no-]traceback</td>
   <td>always print a traceback on exception</td></tr>
   <tr><td></td>
-  <td>--time</td>
+  <td>--[no-]time</td>
   <td>time how long the command takes</td></tr>
   <tr><td></td>
-  <td>--profile</td>
+  <td>--[no-]profile</td>
   <td>print command execution profile</td></tr>
   <tr><td></td>
   <td>--version</td>
@@ -2530,7 +2530,7 @@  Dish up an empty repo; serve it cold.
   <td>--help</td>
   <td>display help and exit</td></tr>
   <tr><td></td>
-  <td>--hidden</td>
+  <td>--[no-]hidden</td>
   <td>consider hidden changesets</td></tr>
   </table>
   
@@ -2661,13 +2661,13 @@  Dish up an empty repo; serve it cold.
   </p>
   <table>
   <tr><td>-A</td>
-  <td>--after</td>
+  <td>--[no-]after</td>
   <td>record delete for missing files</td></tr>
   <tr><td>-f</td>
-  <td>--force</td>
+  <td>--[no-]force</td>
   <td>forget added files, delete modified files</td></tr>
   <tr><td>-S</td>
-  <td>--subrepos</td>
+  <td>--[no-]subrepos</td>
   <td>recurse into subrepositories</td></tr>
   <tr><td>-I</td>
   <td>--include PATTERN [+]</td>
@@ -2690,19 +2690,19 @@  Dish up an empty repo; serve it cold.
   <td>--noninteractive</td>
   <td>do not prompt, automatically pick the first choice for all prompts</td></tr>
   <tr><td>-q</td>
-  <td>--quiet</td>
+  <td>--[no-]quiet</td>
   <td>suppress output</td></tr>
   <tr><td>-v</td>
-  <td>--verbose</td>
+  <td>--[no-]verbose</td>
   <td>enable additional output</td></tr>
   <tr><td></td>
   <td>--config CONFIG [+]</td>
   <td>set/override config option (use 'section.name=value')</td></tr>
   <tr><td></td>
-  <td>--debug</td>
+  <td>--[no-]debug</td>
   <td>enable debugging output</td></tr>
   <tr><td></td>
-  <td>--debugger</td>
+  <td>--[no-]debugger</td>
   <td>start debugger</td></tr>
   <tr><td></td>
   <td>--encoding ENCODE</td>
@@ -2711,13 +2711,13 @@  Dish up an empty repo; serve it cold.
   <td>--encodingmode MODE</td>
   <td>set the charset encoding mode (default: strict)</td></tr>
   <tr><td></td>
-  <td>--traceback</td>
+  <td>--[no-]traceback</td>
   <td>always print a traceback on exception</td></tr>
   <tr><td></td>
-  <td>--time</td>
+  <td>--[no-]time</td>
   <td>time how long the command takes</td></tr>
   <tr><td></td>
-  <td>--profile</td>
+  <td>--[no-]profile</td>
   <td>print command execution profile</td></tr>
   <tr><td></td>
   <td>--version</td>
@@ -2726,7 +2726,7 @@  Dish up an empty repo; serve it cold.
   <td>--help</td>
   <td>display help and exit</td></tr>
   <tr><td></td>
-  <td>--hidden</td>
+  <td>--[no-]hidden</td>
   <td>consider hidden changesets</td></tr>
   </table>