[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 21:55:57 UTC 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