# HG changeset patch
# User Augie Fackler <au...@google.com>
# Date 1473821892 14400
#      Tue Sep 13 22:58:12 2016 -0400
# Node ID bc6e18d8c469a1671c2d6725da5771fed3972323
# Parent  aea18fa52d954e234fdfd1d24d3f37f0cb03dc60
help: mark boolean flags with [?] and explain that they can be negated (RFC)

This is an RFC because I'm still not crazy about how this is
documented - perhaps we should add some text discussing what it means
for a flag to be a boolean flag and be negatable?

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,
@@ -87,11 +88,16 @@ 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:
+            lo += '[?]'
+            multioccur = True
 
         data.append((so, lo, desc))
 
     if multioccur:
-        header += (_(" ([+] can be repeated)"))
+        m = _(
+            " ([+] can be repeated, options marked [?] are boolean flags)")
+        header += (m)
 
     rst = ['\n%s:\n\n' % header]
     rst.extend(minirst.maketable(data, 1))
diff --git a/tests/test-help.t b/tests/test-help.t
--- a/tests/test-help.t
+++ b/tests/test-help.t
@@ -311,26 +311,26 @@ Test short command list with verbose opt
    update, up, checkout, co
                  update working directory (or switch revisions)
   
-  global options ([+] can be repeated):
+  global options ([+] can be repeated, options marked [?] are boolean flags):
   
    -R --repository REPO   repository root directory or name of overlay bundle
                           file
       --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 --quiet[?]          suppress output
+   -v --verbose[?]        enable additional output
       --config CONFIG [+] set/override config option (use 'section.name=value')
-      --debug             enable debugging output
-      --debugger          start debugger
+      --debug[?]          enable debugging output
+      --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
+      --traceback[?]      always print a traceback on exception
+      --time[?]           time how long the command takes
+      --profile[?]        print command execution profile
       --version           output version information and exit
    -h --help              display help and exit
-      --hidden            consider hidden changesets
+      --hidden[?]         consider hidden changesets
   
   (use "hg help" for the full list of commands)
 
@@ -349,12 +349,12 @@ Test short command list with verbose opt
   
       Returns 0 if all files are successfully added.
   
-  options ([+] can be repeated):
+  options ([+] can be repeated, options marked [?] are boolean flags):
   
    -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 --subrepos[?]         recurse into subrepositories
+   -n --dry-run[?]          do not perform actions, just print output
   
   (some details hidden, use --verbose to show complete help)
 
@@ -400,33 +400,33 @@ Verbose help for add
   
       Returns 0 if all files are successfully added.
   
-  options ([+] can be repeated):
+  options ([+] can be repeated, options marked [?] are boolean flags):
   
    -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
-  
-  global options ([+] can be repeated):
+   -S --subrepos[?]         recurse into subrepositories
+   -n --dry-run[?]          do not perform actions, just print output
+  
+  global options ([+] can be repeated, options marked [?] are boolean flags):
   
    -R --repository REPO   repository root directory or name of overlay bundle
                           file
       --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 --quiet[?]          suppress output
+   -v --verbose[?]        enable additional output
       --config CONFIG [+] set/override config option (use 'section.name=value')
-      --debug             enable debugging output
-      --debugger          start debugger
+      --debug[?]          enable debugging output
+      --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
+      --traceback[?]      always print a traceback on exception
+      --time[?]           time how long the command takes
+      --profile[?]        print command execution profile
       --version           output version information and exit
    -h --help              display help and exit
-      --hidden            consider hidden changesets
+      --hidden[?]         consider hidden changesets
 
 Test the textwidth config option
 
@@ -460,12 +460,12 @@ Test help option with version option
   
   add the specified files on the next commit
   
-  options ([+] can be repeated):
+  options ([+] can be repeated, options marked [?] are boolean flags):
   
    -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 --subrepos[?]         recurse into subrepositories
+   -n --dry-run[?]          do not perform actions, just print output
   
   (use "hg add -h" to show more help)
   [255]
@@ -532,25 +532,25 @@ Test command without options
   
       Returns 0 on success.
   
-  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
+  options ([+] can be repeated, options marked [?] are boolean flags):
+  
+   -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
   
   (some details hidden, use --verbose to show complete help)
 
@@ -594,24 +594,24 @@ Test command without options
   
       Returns 0 on success.
   
-  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
+  options ([+] can be repeated, options marked [?] are boolean flags):
+  
+   -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
       --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 --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, options marked [?] are boolean flags):
+  
+    --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, options marked [?] are boolean flags):
   
       --longdesc VALUE 
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
                        xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx (default: 3)
-   -n --               normal desc
+   -n --[?]            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)
+    --dopt[?] option is (DEPRECATED)
   $ hg help -v debugoptEXP | grep eopt
-    --eopt option is (EXPERIMENTAL)
+    --eopt[?] option is (EXPERIMENTAL)
 
 #if gettext
 test deprecated option is hidden with translation with untranslated description
@@ -2461,7 +2461,7 @@ Dish up an empty repo; serve it cold.
   Returns 0 if all files are successfully added.
   </p>
   <p>
-  options ([+] can be repeated):
+  options ([+] can be repeated, options marked [?] are boolean flags):
   </p>
   <table>
   <tr><td>-I</td>
@@ -2471,14 +2471,14 @@ 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>--subrepos[?]</td>
   <td>recurse into subrepositories</td></tr>
   <tr><td>-n</td>
-  <td>--dry-run</td>
+  <td>--dry-run[?]</td>
   <td>do not perform actions, just print output</td></tr>
   </table>
   <p>
-  global options ([+] can be repeated):
+  global options ([+] can be repeated, options marked [?] are boolean flags):
   </p>
   <table>
   <tr><td>-R</td>
@@ -2491,19 +2491,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>--quiet[?]</td>
   <td>suppress output</td></tr>
   <tr><td>-v</td>
-  <td>--verbose</td>
+  <td>--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>--debug[?]</td>
   <td>enable debugging output</td></tr>
   <tr><td></td>
-  <td>--debugger</td>
+  <td>--debugger[?]</td>
   <td>start debugger</td></tr>
   <tr><td></td>
   <td>--encoding ENCODE</td>
@@ -2512,13 +2512,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>--traceback[?]</td>
   <td>always print a traceback on exception</td></tr>
   <tr><td></td>
-  <td>--time</td>
+  <td>--time[?]</td>
   <td>time how long the command takes</td></tr>
   <tr><td></td>
-  <td>--profile</td>
+  <td>--profile[?]</td>
   <td>print command execution profile</td></tr>
   <tr><td></td>
   <td>--version</td>
@@ -2527,7 +2527,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>--hidden[?]</td>
   <td>consider hidden changesets</td></tr>
   </table>
   
@@ -2654,17 +2654,17 @@ Dish up an empty repo; serve it cold.
   Returns 0 on success, 1 if any warnings encountered.
   </p>
   <p>
-  options ([+] can be repeated):
+  options ([+] can be repeated, options marked [?] are boolean flags):
   </p>
   <table>
   <tr><td>-A</td>
-  <td>--after</td>
+  <td>--after[?]</td>
   <td>record delete for missing files</td></tr>
   <tr><td>-f</td>
-  <td>--force</td>
+  <td>--force[?]</td>
   <td>forget added files, delete modified files</td></tr>
   <tr><td>-S</td>
-  <td>--subrepos</td>
+  <td>--subrepos[?]</td>
   <td>recurse into subrepositories</td></tr>
   <tr><td>-I</td>
   <td>--include PATTERN [+]</td>
@@ -2674,7 +2674,7 @@ Dish up an empty repo; serve it cold.
   <td>exclude names matching the given patterns</td></tr>
   </table>
   <p>
-  global options ([+] can be repeated):
+  global options ([+] can be repeated, options marked [?] are boolean flags):
   </p>
   <table>
   <tr><td>-R</td>
@@ -2687,19 +2687,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>--quiet[?]</td>
   <td>suppress output</td></tr>
   <tr><td>-v</td>
-  <td>--verbose</td>
+  <td>--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>--debug[?]</td>
   <td>enable debugging output</td></tr>
   <tr><td></td>
-  <td>--debugger</td>
+  <td>--debugger[?]</td>
   <td>start debugger</td></tr>
   <tr><td></td>
   <td>--encoding ENCODE</td>
@@ -2708,13 +2708,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>--traceback[?]</td>
   <td>always print a traceback on exception</td></tr>
   <tr><td></td>
-  <td>--time</td>
+  <td>--time[?]</td>
   <td>time how long the command takes</td></tr>
   <tr><td></td>
-  <td>--profile</td>
+  <td>--profile[?]</td>
   <td>print command execution profile</td></tr>
   <tr><td></td>
   <td>--version</td>
@@ -2723,7 +2723,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>--hidden[?]</td>
   <td>consider hidden changesets</td></tr>
   </table>
   
_______________________________________________
Mercurial-devel mailing list
Mercurial-devel@mercurial-scm.org
https://www.mercurial-scm.org/mailman/listinfo/mercurial-devel

Reply via email to