From patchwork Wed Sep 14 03:11:23 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: [7, of, 7, v3, flags] help: mark boolean flags with [?] and explain that they can be negated (RFC) From: Augie Fackler X-Patchwork-Id: 16620 Message-Id: <03685e9da0e6085ef1fe.1473822683@augie-macbookair2.roam.corp.google.com> To: mercurial-devel@mercurial-scm.org Date: Tue, 13 Sep 2016 23:11:23 -0400 # HG changeset patch # User Augie Fackler # Date 1473821892 14400 # Tue Sep 13 22:58:12 2016 -0400 # Node ID 03685e9da0e6085ef1feff99a1c6fd994f41b620 # Parent e6d239fd14a1065f9cf05dc0b45be41408b306a4 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.

- options ([+] can be repeated): + options ([+] can be repeated, options marked [?] are boolean flags):

@@ -2471,14 +2471,14 @@ Dish up an empty repo; serve it cold. - + - +
-I--exclude PATTERN [+] exclude names matching the given patterns
-S--subrepos--subrepos[?] recurse into subrepositories
-n--dry-run--dry-run[?] do not perform actions, just print output

- global options ([+] can be repeated): + global options ([+] can be repeated, options marked [?] are boolean flags):

@@ -2491,19 +2491,19 @@ Dish up an empty repo; serve it cold. - + - + - + - + @@ -2512,13 +2512,13 @@ Dish up an empty repo; serve it cold. - + - + - + @@ -2527,7 +2527,7 @@ Dish up an empty repo; serve it cold. - +
-R--noninteractive do not prompt, automatically pick the first choice for all prompts
-q--quiet--quiet[?] suppress output
-v--verbose--verbose[?] enable additional output
--config CONFIG [+] set/override config option (use 'section.name=value')
--debug--debug[?] enable debugging output
--debugger--debugger[?] start debugger
--encoding ENCODE--encodingmode MODE set the charset encoding mode (default: strict)
--traceback--traceback[?] always print a traceback on exception
--time--time[?] time how long the command takes
--profile--profile[?] print command execution profile
--version--help display help and exit
--hidden--hidden[?] consider hidden changesets
@@ -2654,17 +2654,17 @@ Dish up an empty repo; serve it cold. Returns 0 on success, 1 if any warnings encountered.

- options ([+] can be repeated): + options ([+] can be repeated, options marked [?] are boolean flags):

- + - + - + @@ -2674,7 +2674,7 @@ Dish up an empty repo; serve it cold.
-A--after--after[?] record delete for missing files
-f--force--force[?] forget added files, delete modified files
-S--subrepos--subrepos[?] recurse into subrepositories
-I --include PATTERN [+]exclude names matching the given patterns

- global options ([+] can be repeated): + global options ([+] can be repeated, options marked [?] are boolean flags):

@@ -2687,19 +2687,19 @@ Dish up an empty repo; serve it cold. - + - + - + - + @@ -2708,13 +2708,13 @@ Dish up an empty repo; serve it cold. - + - + - + @@ -2723,7 +2723,7 @@ Dish up an empty repo; serve it cold. - +
-R--noninteractive do not prompt, automatically pick the first choice for all prompts
-q--quiet--quiet[?] suppress output
-v--verbose--verbose[?] enable additional output
--config CONFIG [+] set/override config option (use 'section.name=value')
--debug--debug[?] enable debugging output
--debugger--debugger[?] start debugger
--encoding ENCODE--encodingmode MODE set the charset encoding mode (default: strict)
--traceback--traceback[?] always print a traceback on exception
--time--time[?] time how long the command takes
--profile--profile[?] print command execution profile
--version--help display help and exit
--hidden--hidden[?] consider hidden changesets