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

Augie Fackler raf at durin42.com
Tue Sep 27 17:55:57 EDT 2016


# HG changeset patch
# User Augie Fackler <augie at 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.

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>
   


More information about the Mercurial-devel mailing list