git/Documentation/technical/api-parse-options.txt, branch v1.8.2.2

Documentation: the name of the system is 'Git', not 'git'

2013-02-01T21:53:33Z

Signed-off-by: Thomas Ackermann Signed-off-by: Junio C Hamano

docs: stop using asciidoc no-inline-literal

2012-04-26T20:19:06Z

In asciidoc 7, backticks like `foo` produced a typographic effect, but did not otherwise affect the syntax. In asciidoc 8, backticks introduce an "inline literal" inside which markup is not interpreted. To keep compatibility with existing documents, asciidoc 8 has a "no-inline-literal" attribute to keep the old behavior. We enabled this so that the documentation could be built on either version. It has been several years now, and asciidoc 7 is no longer in wide use. We can now decide whether or not we want inline literals on their own merits, which are: 1. The source is much easier to read when the literal contains punctuation. You can use `master~1` instead of `master{tilde}1`. 2. They are less error-prone. Because of point (1), we tend to make mistakes and forget the extra layer of quoting. This patch removes the no-inline-literal attribute from the Makefile and converts every use of backticks in the documentation to an inline literal (they must be cleaned up, or the example above would literally show "{tilde}" in the output). Problematic sites were found by grepping for '`.*[{\\]' and examined and fixed manually. The results were then verified by comparing the output of "html2text" on the set of generated html pages. Doing so revealed that in addition to making the source more readable, this patch fixes several formatting bugs: - HTML rendering used the ellipsis character instead of literal "..." in code examples (like "git log A...B") - some code examples used the right-arrow character instead of '->' because they failed to quote - api-config.txt did not quote tilde, and the resulting HTML contained a bogus snippet like: foo bar which caused some parsers to choke and omit whole sections of the page. - git-commit.txt confused ``foo`` (backticks inside a literal) with ``foo'' (matched double-quotes) - mentions of `A U Thor ` used to erroneously auto-generate a mailto footnote for author@example.com - the description of --word-diff=plain incorrectly showed the output as "[-removed-] and {added}", not "{+added+}". - using "prime" notation like: commit `C` and its replacement `C'` confused asciidoc into thinking that everything between the first backtick and the final apostrophe were meant to be inside matched quotes - asciidoc got confused by the escaping of some of our asterisks. In particular, `credential.\*` and `credential..\*` properly escaped the asterisk in the first case, but literally passed through the backslash in the second case. Signed-off-by: Jeff King Signed-off-by: Junio C Hamano

parse-options: allow positivation of options starting, with no-

2012-02-26T23:32:53Z

Long options can be negated by adding no- right after the leading two dashes. This is useful e.g. to override options set by aliases. For options that are defined to start with no- already, this looks a bit funny. Allow such options to also be negated by removing the prefix. The following thirteen options are affected: apply --no-add bisect--helper --no-checkout checkout-index --no-create clone --no-checkout --no-hardlinks commit --no-verify --no-post-rewrite format-patch --no-binary hash-object --no-filters read-tree --no-sparse-checkout revert --no-commit show-branch --no-name update-ref --no-deref The following five are NOT affected because they are defined with PARSE_OPT_NONEG or the non-negated version is defined as well: branch --no-merged format-patch --no-stat --no-numbered update-index --no-assume-unchanged --no-skip-worktree Signed-off-by: Rene Scharfe Signed-off-by: Junio C Hamano

parseopt: add OPT_NOOP_NOARG

2011-09-28T19:46:21Z

Add OPT_NOOP_NOARG, a helper macro to define deprecated options in a standard way. The help text is taken from the no-op option -r of git revert. The callback could be made to emit a (conditional?) warning later. And we could also add OPT_NOOP (requiring an argument) etc. as needed. Signed-off-by: Rene Scharfe Signed-off-by: Junio C Hamano

parse-options: deprecate OPT_BOOLEAN

2011-09-28T00:00:04Z

It is natural to expect that an option defined with OPT_BOOLEAN() could be used in this way: int option = -1; /* unspecified */ struct option options[] = { OPT_BOOLEAN(0, "option", &option, "set option"), OPT_END() }; parse_options(ac, av, prefix, options, usage, 0); if (option < 0) ... do the default thing ... else if (!option) ... --no-option was given ... else ... --option was given ... to easily tell three cases apart: - There is no mention of the `--option` on the command line; - The variable is positively set with `--option`; or - The variable is explicitly negated with `--no-option`. Unfortunately, this is not the case. OPT_BOOLEAN() increments the variable every time `--option` is given, and resets it to zero when `--no-option` is given. As a first step to remedy this, introduce a true boolean OPT_BOOL(), and rename OPT_BOOLEAN() to OPT_COUNTUP(). To help transitioning, OPT_BOOLEAN and OPTION_BOOLEAN are defined as deprecated synonyms to OPT_COUNTUP and OPTION_COUNTUP respectively. This is what db7244b (parse-options new features., 2007-11-07) from four years ago started by marking OPTION_BOOLEAN as "INCR would have been a better name". Some existing users do depend on the count-up semantics; for example, users of OPT__VERBOSE() could use it to raise the verbosity level with repeated use of `-v` on the command line, but they probably should be rewritten to use OPT__VERBOSITY() instead these days. I suspect that some users of OPT__FORCE() may also use it to implement different level of forcibleness but I didn't check. On top of this patch, here are the remaining clean-up tasks that other people can help: - Look at each hit in "git grep -e OPT_BOOLEAN"; trace all uses of the value that is set to the underlying variable, and if it can proven that the variable is only used as a boolean, replace it with OPT_BOOL(). If the caller does depend on the count-up semantics, replace it with OPT_COUNTUP() instead. - Same for OPTION_BOOLEAN; replace it with OPTION_SET_INT and arrange to set 1 to the variable for a true boolean, and otherwise replace it with OPTION_COUNTUP. - Look at each hit in "git grep -e OPT__VERBOSE -e OPT__QUIET" and see if they can be replaced with OPT__VERBOSITY(). I'll follow this message up with a separate patch as an example. Signed-off-by: Junio C Hamano

add OPT__FORCE

2010-11-15T18:04:43Z

Add OPT__FORCE as a helper macro in the same spirit as OPT__VERBOSE et.al. to simplify defining -f/--force options. Signed-off-by: Rene Scharfe Signed-off-by: Junio C Hamano

add description parameter to OPT__QUIET

2010-11-15T17:58:13Z

Allows better help text to be defined than "be quiet". Also make use of the macro in a place that already had a different description. No object code changes intended. Signed-off-by: Rene Scharfe Signed-off-by: Junio C Hamano

add description parameter to OPT__DRY_RUN

2010-11-15T17:57:37Z

Allows better help text to be defined than "dry run". Also make use of the macro in places that already had a different description. No object code changes intended. Signed-off-by: Rene Scharfe Signed-off-by: Junio C Hamano

add description parameter to OPT__VERBOSE

2010-11-15T17:56:51Z

Allows better help text to be defined than "be verbose". Also make use of the macro in places that already had a different description. No object code changes intended. Signed-off-by: Rene Scharfe Signed-off-by: Junio C Hamano

Documentation/technical: avoid stray backslash in parse-options API docs

2010-08-20T21:16:22Z

Due to some unpleasant interaction between the `quote', 'italics', and `monospace` rules, a certain paragraph ends up rendered like so: ‘short` is a character for the short option (e.g. 'e\’ for -e, use 0 to omit), Use the {apostrophe} to avoid this. While at it, escape "->" strings: they are meant as a literal two-character C operator, not a right-pointing arrow. Reported-by: Frédéric Brière Signed-off-by: Jonathan Nieder Signed-off-by: Junio C Hamano