[RFH] convert shortlog to use parse_options

@@ -6,9 +6,12 @@
 #include "revision.h"
 #include "utf8.h"
 #include "mailmap.h"
+#include "parse-options.h"
 
-static const char shortlog_usage[] =
-"git-shortlog [-n] [-s] [<commit-id>... ]";
+static const char * const shortlog_usage[] = {
+	"git-shortlog [-n] [-s] [-e] [<commit-id>... ]",
+	NULL
+};
 
 static char *common_repo_prefix;
 static int email;

@@ -181,34 +184,45 @@ static int parse_uint(char const **arg, int comma)
 }
 
 static const char wrap_arg_usage[] = "-w[<width>[,<indent1>[,<indent2>]]]";
+struct wrap_arg {
+	int enabled;
+	int len;
+	int in1;
+	int in2;
+};
 #define DEFAULT_WRAPLEN 76
 #define DEFAULT_INDENT1 6
 #define DEFAULT_INDENT2 9
 
-static void parse_wrap_args(const char *arg, int *in1, int *in2, int *wrap)
+static int parse_wrap(const struct option *opt, const char *arg, int unset)
 {
-	arg += 2; /* skip -w */
+	struct wrap_arg *wrap = opt->value;
 
-	*wrap = parse_uint(&arg, ',');
-	if (*wrap < 0)
+	wrap->enabled = 1;
+
+	if (!arg)
+		return 0;
+	wrap->len = parse_uint(&arg, ',');
+	if (wrap->len < 0)
 		die(wrap_arg_usage);
-	*in1 = parse_uint(&arg, ',');
-	if (*in1 < 0)
+	wrap->in1 = parse_uint(&arg, ',');
+	if (wrap->in1 < 0)
 		die(wrap_arg_usage);
-	*in2 = parse_uint(&arg, '\0');
-	if (*in2 < 0)
+	wrap->in2 = parse_uint(&arg, '\0');
+	if (wrap->in2 < 0)
 		die(wrap_arg_usage);
 
-	if (!*wrap)
-		*wrap = DEFAULT_WRAPLEN;
-	if (!*in1)
-		*in1 = DEFAULT_INDENT1;
-	if (!*in2)
-		*in2 = DEFAULT_INDENT2;
-	if (*wrap &&
-	    ((*in1 && *wrap <= *in1) ||
-	     (*in2 && *wrap <= *in2)))
+	if (!wrap->len)
+		wrap->len = DEFAULT_WRAPLEN;
+	if (!wrap->in1)
+		wrap->in1 = DEFAULT_INDENT1;
+	if (!wrap->in2)
+		wrap->in2 = DEFAULT_INDENT2;
+	if (wrap->len &&
+	    ((wrap->in1 && wrap->len <= wrap->in1) ||
+	     (wrap->in2 && wrap->len <= wrap->in2)))
 		die(wrap_arg_usage);
+	return 0;
 }
 
 int cmd_shortlog(int argc, const char **argv, const char *prefix)

@@ -216,34 +230,31 @@ int cmd_shortlog(int argc, const char **argv, const char *prefix)
 	struct rev_info rev;
 	struct path_list list = { NULL, 0, 0, 1 };
 	int i, j, sort_by_number = 0, summary = 0;
-	int wrap_lines = 0;
-	int wrap = DEFAULT_WRAPLEN;
-	int in1 = DEFAULT_INDENT1;
-	int in2 = DEFAULT_INDENT2;
-
-	/* since -n is a shadowed rev argument, parse our args first */
-	while (argc > 1) {
-		if (!strcmp(argv[1], "-n") || !strcmp(argv[1], "--numbered"))
-			sort_by_number = 1;
-		else if (!strcmp(argv[1], "-s") ||
-				!strcmp(argv[1], "--summary"))
-			summary = 1;
-		else if (!strcmp(argv[1], "-e") ||
-			 !strcmp(argv[1], "--email"))
-			email = 1;
-		else if (!prefixcmp(argv[1], "-w")) {
-			wrap_lines = 1;
-			parse_wrap_args(argv[1], &in1, &in2, &wrap);
-		}
-		else if (!strcmp(argv[1], "-h") || !strcmp(argv[1], "--help"))
-			usage(shortlog_usage);
-		else
-			break;
-		argv++;
-		argc--;
-	}
+	struct wrap_arg wrap = {
+		0,
+		DEFAULT_WRAPLEN,
+		DEFAULT_INDENT1,
+		DEFAULT_INDENT2
+	};
+	struct option options[] = {
+		OPT_BOOLEAN('n', "numbered", &sort_by_number, "sort by number"),
+		OPT_BOOLEAN('s', "summary", &summary,
+				"show commit count summary"),
+		OPT_BOOLEAN('e', "email", &email, "show email addresses"),
+		{
+			OPTION_CALLBACK, 'w', NULL, &wrap, "wrap",
+			"line-wrap commit message", PARSE_OPT_OPTARG,
+			parse_wrap
+		},
+	};
+
+	argc = parse_options(argc, argv, options, shortlog_usage, 0);
+
 	init_revisions(&rev, prefix);
-	argc = setup_revisions(argc, argv, &rev, NULL);
+	/* setup_revisions expects to have the program name in argv[0],
+	 * but parse_options has removed it. We have to do parse_options
+	 * before setup_revisions, though, to claim "-n". */
+	argc = setup_revisions(argc+1, argv-1, &rev, NULL);
 	if (argc > 1)
 		die ("unrecognized argument: %s", argv[1]);
 

@@ -272,9 +283,11 @@ int cmd_shortlog(int argc, const char **argv, const char *prefix)
 			for (j = onelines->nr - 1; j >= 0; j--) {
 				const char *msg = onelines->items[j].path;
 
-				if (wrap_lines) {
-					int col = print_wrapped_text(msg, in1, in2, wrap);
-					if (col != wrap)
+				if (wrap.enabled) {
+					int col = print_wrapped_text(msg,
+							wrap.in1, wrap.in2,
+							wrap.len);
+					if (col != wrap.len)
 						putchar('\n');
 				}
 				else

@@ -89,7 +89,7 @@ static int get_value(struct optparse_t *p,
 			*(const char **)opt->value = NULL;
 			return 0;
 		}
-		if (opt->flags & PARSE_OPT_OPTARG && (!arg || *arg == '-')) {
+		if (opt->flags & PARSE_OPT_OPTARG && !p->opt) {
 			*(const char **)opt->value = (const char *)opt->defval;
 			return 0;
 		}

@@ -103,7 +103,7 @@ static int get_value(struct optparse_t *p,
 			return (*opt->callback)(opt, NULL, 1);
 		if (opt->flags & PARSE_OPT_NOARG)
 			return (*opt->callback)(opt, NULL, 0);
-		if (opt->flags & PARSE_OPT_OPTARG && (!arg || *arg == '-'))
+		if (opt->flags & PARSE_OPT_OPTARG && !p->opt)
 			return (*opt->callback)(opt, NULL, 0);
 		if (!arg)
 			return opterror(opt, "requires a value", flags);

@@ -114,7 +114,7 @@ static int get_value(struct optparse_t *p,
 			*(int *)opt->value = 0;
 			return 0;
 		}
-		if (opt->flags & PARSE_OPT_OPTARG && (!arg || !isdigit(*arg))) {
+		if (opt->flags & PARSE_OPT_OPTARG && !p->opt) {
 			*(int *)opt->value = opt->defval;
 			return 0;
 		}

@@ -2,7 +2,7 @@ MAN1_TXT= \
 	$(filter-out $(addsuffix .txt, $(ARTICLES) $(SP_ARTICLES)), \
 		$(wildcard git-*.txt)) \
 	gitk.txt
-MAN5_TXT=gitattributes.txt gitignore.txt gitmodules.txt
+MAN5_TXT=gitattributes.txt gitignore.txt gitcli.txt gitmodules.txt
 MAN7_TXT=git.txt
 
 MAN_TXT = $(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT)

@@ -0,0 +1,104 @@
+gitcli(5)
+=========
+
+NAME
+----
+gitcli - git command line interface and its usual conventions
+
+SYNOPSIS
+--------
+gitcli
+
+
+DESCRIPTION
+-----------
+This manual intends to describe best practice in how to use git CLI.  Here are
+the rules that you should follow when you are scripting git:
+
+ * it's preferred to use the non dashed form of git commands, which means that
+   you should prefer `"git foo"` to `"git-foo"`.
+
+ * splitting short option switches in separate atoms (prefer `"git foo -a -b"`
+   to `"git foo -ab"`, the latter may not even work).
+
+ * when a command line switch takes an argument, use the 'sticked' form, which
+   means that you must prefer `"git foo -oArg"` to `"git foo -o Arg"` for short
+   option switches, and `"git foo --long-opt=Arg"` to `"git foo --long-opt Arg"`
+   for long switches.
+
+
+ENHANCED CLI
+------------
+From the git 1.5.4 series and further, git commands (not all of them at the
+time of the writing though) come with an enhanced option parser with nice
+facilities. Here is an exhaustive list of them
+
+Magic Options
+~~~~~~~~~~~~~
+Commands which have the enhanced option parser activated all understand a
+couple of magic command line switches:
+
+-h::
+	gives a pretty printed usage of the command.
++
+---------------------------------------------
+$ git describe -h
+usage: git-describe [options] <committish>*
+
+    --contains            find the tag that comes after the commit
+    --debug               debug search strategy on stderr
+    --all                 use any ref in .git/refs
+    --tags                use any tag in .git/refs/tags
+    --abbrev [<n>]        use <n> digits to display SHA-1s
+    --candidates <n>      consider <n> most recent tags (default: 10)
+---------------------------------------------
+
+--help-all::
+	Some git commands takes options that are only used for plumbing or that
+	are deprecated, and such options are hidden from the default usage. This
+	switch gives the full list of options.
+
+
+Negating options
+~~~~~~~~~~~~~~~~
+Another things to keep in mind is that long options can be negated. For
+example, `"git branch"` has the option `"--track"` which is 'on' by default. You
+can use `"--no-track"` to override that behaviour. The same goes for `"--color"`
+and `"--no-color"`.
+
+
+Aggregating short options
+~~~~~~~~~~~~~~~~~~~~~~~~~
+Commands that support the enhanced option parser allow you to aggregate short
+options. This means that you can for example use `"git rm -rf"` or
+`"git clean -fdx"`.
+
+
+Separating argument from the switch
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Also for option switches that take a mandatory argument, you can separate it
+from the switch. That means that all the following uses are correct:
+
+----------------------------
+$ git foo --long-opt=Arg
+$ git foo --long-opt Arg
+$ git foo -oArg
+$ git foo -o Arg
+----------------------------
+
+However, this is *NOT* possible for switches with an optionnal value, where the
+'sticked' form must be used:
+----------------------------
+$ git describe --abbrev HEAD     # correct
+$ git describe --abbrev=10 HEAD  # correct
+$ git describe --abbrev 10 HEAD  # NOT WHAT YOU MEANT
+----------------------------
+
+
+Documentation
+-------------
+Documentation by Pierre Habouzit.
+
+GIT
+---
+Part of the gitlink:git[7] suite

@@ -371,7 +371,7 @@ int cmd_tag(int argc, const char **argv, const char *prefix)
 
 	int annotate = 0, sign = 0, force = 0, lines = 0,
 					delete = 0, verify = 0;
-	char *list = NULL, *msgfile = NULL, *keyid = NULL;
+	const char *list = NULL, *msgfile = NULL, *keyid = NULL;
 	const char *no_pattern = "NO_PATTERN";
 	struct msg_arg msg = { 0, STRBUF_INIT };
 	struct option options[] = {

@@ -407,8 +407,19 @@ int cmd_tag(int argc, const char **argv, const char *prefix)
 	if (sign)
 		annotate = 1;
 
-	if (list)
+	if (list) {
+		/*
+		 * This is unfortunate but requiring "git tag -lpattern" and not
+		 * allowing "git tag -l pattern" is a serious regression.
+		 */
+		if (argc && list == no_pattern) {
+			list = argv[0];
+			argc--;
+		}
+		if (argc)
+			die("extra argument after -l[pattern]: %s", argv[0]);
 		return list_tags(list == no_pattern ? NULL : list, lines);
+	}
 	if (delete)
 		return for_each_tag_name(argv, delete_tag);
 	if (verify)

@@ -491,25 +491,19 @@ test_expect_success \
 	echo "tag-one-line" >expect &&
 	git-tag -l | grep "^tag-one-line" >actual &&
 	git diff expect actual &&
-	git-tag -n 0 -l | grep "^tag-one-line" >actual &&
+	git-tag -n0 -l | grep "^tag-one-line" >actual &&
 	git diff expect actual &&
-	git-tag -n 0 -l tag-one-line >actual &&
+	git-tag -n0 -l tag-one-line >actual &&
 	git diff expect actual &&
 
 	echo "tag-one-line    A msg" >expect &&
-	git-tag -n xxx -l | grep "^tag-one-line" >actual &&
-	git diff expect actual &&
-	git-tag -n "" -l | grep "^tag-one-line" >actual &&
-	git diff expect actual &&
-	git-tag -n 1 -l | grep "^tag-one-line" >actual &&
-	git diff expect actual &&
 	git-tag -n -l | grep "^tag-one-line" >actual &&
 	git diff expect actual &&
-	git-tag -n 1 -l tag-one-line >actual &&
+	git-tag -n1 -l | grep "^tag-one-line" >actual &&
 	git diff expect actual &&
-	git-tag -n 2 -l tag-one-line >actual &&
+	git-tag -n2 -l tag-one-line >actual &&
 	git diff expect actual &&
-	git-tag -n 999 -l tag-one-line >actual &&
+	git-tag -n999 -l tag-one-line >actual &&
 	git diff expect actual
 '
 

@@ -520,21 +514,21 @@ test_expect_success \
 	echo "tag-zero-lines" >expect &&
 	git-tag -l | grep "^tag-zero-lines" >actual &&
 	git diff expect actual &&
-	git-tag -n 0 -l | grep "^tag-zero-lines" >actual &&
+	git-tag -n0 -l | grep "^tag-zero-lines" >actual &&
 	git diff expect actual &&
-	git-tag -n 0 -l tag-zero-lines >actual &&
+	git-tag -n0 -l tag-zero-lines >actual &&
 	git diff expect actual &&
 
 	echo "tag-zero-lines  " >expect &&
-	git-tag -n 1 -l | grep "^tag-zero-lines" >actual &&
+	git-tag -n1 -l | grep "^tag-zero-lines" >actual &&
 	git diff expect actual &&
 	git-tag -n -l | grep "^tag-zero-lines" >actual &&
 	git diff expect actual &&
-	git-tag -n 1 -l tag-zero-lines >actual &&
+	git-tag -n1 -l tag-zero-lines >actual &&
 	git diff expect actual &&
-	git-tag -n 2 -l tag-zero-lines >actual &&
+	git-tag -n2 -l tag-zero-lines >actual &&
 	git diff expect actual &&
-	git-tag -n 999 -l tag-zero-lines >actual &&
+	git-tag -n999 -l tag-zero-lines >actual &&
 	git diff expect actual
 '
 

@@ -548,37 +542,37 @@ test_expect_success \
 	echo "tag-lines" >expect &&
 	git-tag -l | grep "^tag-lines" >actual &&
 	git diff expect actual &&
-	git-tag -n 0 -l | grep "^tag-lines" >actual &&
+	git-tag -n0 -l | grep "^tag-lines" >actual &&
 	git diff expect actual &&
-	git-tag -n 0 -l tag-lines >actual &&
+	git-tag -n0 -l tag-lines >actual &&
 	git diff expect actual &&
 
 	echo "tag-lines       tag line one" >expect &&
-	git-tag -n 1 -l | grep "^tag-lines" >actual &&
+	git-tag -n1 -l | grep "^tag-lines" >actual &&
 	git diff expect actual &&
 	git-tag -n -l | grep "^tag-lines" >actual &&
 	git diff expect actual &&
-	git-tag -n 1 -l tag-lines >actual &&
+	git-tag -n1 -l tag-lines >actual &&
 	git diff expect actual &&
 
 	echo "    tag line two" >>expect &&
-	git-tag -n 2 -l | grep "^ *tag.line" >actual &&
+	git-tag -n2 -l | grep "^ *tag.line" >actual &&
 	git diff expect actual &&
-	git-tag -n 2 -l tag-lines >actual &&
+	git-tag -n2 -l tag-lines >actual &&
 	git diff expect actual &&
 
 	echo "    tag line three" >>expect &&
-	git-tag -n 3 -l | grep "^ *tag.line" >actual &&
+	git-tag -n3 -l | grep "^ *tag.line" >actual &&
 	git diff expect actual &&
-	git-tag -n 3 -l tag-lines >actual &&
+	git-tag -n3 -l tag-lines >actual &&
 	git diff expect actual &&
-	git-tag -n 4 -l | grep "^ *tag.line" >actual &&
+	git-tag -n4 -l | grep "^ *tag.line" >actual &&
 	git diff expect actual &&
-	git-tag -n 4 -l tag-lines >actual &&
+	git-tag -n4 -l tag-lines >actual &&
 	git diff expect actual &&
-	git-tag -n 99 -l | grep "^ *tag.line" >actual &&
+	git-tag -n99 -l | grep "^ *tag.line" >actual &&
 	git diff expect actual &&
-	git-tag -n 99 -l tag-lines >actual &&
+	git-tag -n99 -l tag-lines >actual &&
 	git diff expect actual
 '
 

@@ -906,25 +900,21 @@ test_expect_success \
 	echo "stag-one-line" >expect &&
 	git-tag -l | grep "^stag-one-line" >actual &&
 	git diff expect actual &&
-	git-tag -n 0 -l | grep "^stag-one-line" >actual &&
+	git-tag -n0 -l | grep "^stag-one-line" >actual &&
 	git diff expect actual &&
-	git-tag -n 0 -l stag-one-line >actual &&
+	git-tag -n0 -l stag-one-line >actual &&
 	git diff expect actual &&
 
 	echo "stag-one-line   A message line signed" >expect &&
-	git-tag -n xxx -l | grep "^stag-one-line" >actual &&
-	git diff expect actual &&
-	git-tag -n "" -l | grep "^stag-one-line" >actual &&
-	git diff expect actual &&
-	git-tag -n 1 -l | grep "^stag-one-line" >actual &&
-	git diff expect actual &&
 	git-tag -n -l | grep "^stag-one-line" >actual &&
 	git diff expect actual &&
-	git-tag -n 1 -l stag-one-line >actual &&
+	git-tag -n1 -l | grep "^stag-one-line" >actual &&
 	git diff expect actual &&
-	git-tag -n 2 -l stag-one-line >actual &&
+	git-tag -n1 -l stag-one-line >actual &&
 	git diff expect actual &&
-	git-tag -n 999 -l stag-one-line >actual &&
+	git-tag -n2 -l stag-one-line >actual &&
+	git diff expect actual &&
+	git-tag -n999 -l stag-one-line >actual &&
 	git diff expect actual
 '
 

@@ -935,21 +925,21 @@ test_expect_success \
 	echo "stag-zero-lines" >expect &&
 	git-tag -l | grep "^stag-zero-lines" >actual &&
 	git diff expect actual &&
-	git-tag -n 0 -l | grep "^stag-zero-lines" >actual &&
+	git-tag -n0 -l | grep "^stag-zero-lines" >actual &&
 	git diff expect actual &&
-	git-tag -n 0 -l stag-zero-lines >actual &&
+	git-tag -n0 -l stag-zero-lines >actual &&
 	git diff expect actual &&
 
 	echo "stag-zero-lines " >expect &&
-	git-tag -n 1 -l | grep "^stag-zero-lines" >actual &&
-	git diff expect actual &&
 	git-tag -n -l | grep "^stag-zero-lines" >actual &&
 	git diff expect actual &&
-	git-tag -n 1 -l stag-zero-lines >actual &&
+	git-tag -n1 -l | grep "^stag-zero-lines" >actual &&
+	git diff expect actual &&
+	git-tag -n1 -l stag-zero-lines >actual &&
 	git diff expect actual &&
-	git-tag -n 2 -l stag-zero-lines >actual &&
+	git-tag -n2 -l stag-zero-lines >actual &&
 	git diff expect actual &&
-	git-tag -n 999 -l stag-zero-lines >actual &&
+	git-tag -n999 -l stag-zero-lines >actual &&
 	git diff expect actual
 '
 

@@ -963,37 +953,37 @@ test_expect_success \
 	echo "stag-lines" >expect &&
 	git-tag -l | grep "^stag-lines" >actual &&
 	git diff expect actual &&
-	git-tag -n 0 -l | grep "^stag-lines" >actual &&
+	git-tag -n0 -l | grep "^stag-lines" >actual &&
 	git diff expect actual &&
-	git-tag -n 0 -l stag-lines >actual &&
+	git-tag -n0 -l stag-lines >actual &&
 	git diff expect actual &&
 
 	echo "stag-lines      stag line one" >expect &&
-	git-tag -n 1 -l | grep "^stag-lines" >actual &&
-	git diff expect actual &&
 	git-tag -n -l | grep "^stag-lines" >actual &&
 	git diff expect actual &&
-	git-tag -n 1 -l stag-lines >actual &&
+	git-tag -n1 -l | grep "^stag-lines" >actual &&
+	git diff expect actual &&
+	git-tag -n1 -l stag-lines >actual &&
 	git diff expect actual &&
 
 	echo "    stag line two" >>expect &&
-	git-tag -n 2 -l | grep "^ *stag.line" >actual &&
+	git-tag -n2 -l | grep "^ *stag.line" >actual &&
 	git diff expect actual &&
-	git-tag -n 2 -l stag-lines >actual &&
+	git-tag -n2 -l stag-lines >actual &&
 	git diff expect actual &&
 
 	echo "    stag line three" >>expect &&
-	git-tag -n 3 -l | grep "^ *stag.line" >actual &&
+	git-tag -n3 -l | grep "^ *stag.line" >actual &&
 	git diff expect actual &&
-	git-tag -n 3 -l stag-lines >actual &&
+	git-tag -n3 -l stag-lines >actual &&
 	git diff expect actual &&
-	git-tag -n 4 -l | grep "^ *stag.line" >actual &&
+	git-tag -n4 -l | grep "^ *stag.line" >actual &&
 	git diff expect actual &&
-	git-tag -n 4 -l stag-lines >actual &&
+	git-tag -n4 -l stag-lines >actual &&
 	git diff expect actual &&
-	git-tag -n 99 -l | grep "^ *stag.line" >actual &&
+	git-tag -n99 -l | grep "^ *stag.line" >actual &&
 	git diff expect actual &&
-	git-tag -n 99 -l stag-lines >actual &&
+	git-tag -n99 -l stag-lines >actual &&
 	git diff expect actual
 '
 

@@ -3,7 +3,7 @@ gitcli(5)
 
 NAME
 ----
-gitcli - git command line interface and its usual conventions
+gitcli - git command line interface and conventions
 
 SYNOPSIS
 --------

@@ -12,31 +12,40 @@ gitcli
 
 DESCRIPTION
 -----------
-This manual intends to describe best practice in how to use git CLI.  Here are
+
+This manual describes best practice in how to use git CLI.  Here are
 the rules that you should follow when you are scripting git:
 
  * it's preferred to use the non dashed form of git commands, which means that
    you should prefer `"git foo"` to `"git-foo"`.
 
- * splitting short option switches in separate atoms (prefer `"git foo -a -b"`
+ * splitting short options to separate words (prefer `"git foo -a -b"`
    to `"git foo -ab"`, the latter may not even work).
 
- * when a command line switch takes an argument, use the 'sticked' form, which
-   means that you must prefer `"git foo -oArg"` to `"git foo -o Arg"` for short
-   option switches, and `"git foo --long-opt=Arg"` to `"git foo --long-opt Arg"`
-   for long switches.
+ * when a command line option takes an argument, use the 'sticked' form.  In
+   other words, write `"git foo -oArg"` instead of `"git foo -o Arg"` for short
+   options, and `"git foo --long-opt=Arg"` instead of `"git foo --long-opt Arg"`
+   for long options.  An option that takes optional option-argument must be
+   written in the 'sticked' form.
+
+ * when you give a revision parameter to a command, make sure the parameter is
+   not ambiguous with a name of a file in the work tree.  E.g. do not write
+   `"git log -1 HEAD"` but write `"git log -1 HEAD --"`; the former will not work
+   if you happen to have a file called `HEAD` in the work tree.
 
 
 ENHANCED CLI
 ------------
-From the git 1.5.4 series and further, git commands (not all of them at the
-time of the writing though) come with an enhanced option parser with nice
-facilities. Here is an exhaustive list of them
+From the git 1.5.4 series and further, many git commands (not all of them at the
+time of the writing though) come with an enhanced option parser.
+
+Here is an exhaustive list of the facilities provided by this option parser.
+
 
 Magic Options
 ~~~~~~~~~~~~~
 Commands which have the enhanced option parser activated all understand a
-couple of magic command line switches:
+couple of magic command line options:
 
 -h::
 	gives a pretty printed usage of the command.

@@ -54,14 +63,14 @@ usage: git-describe [options] <committish>*
 ---------------------------------------------
 
 --help-all::
-	Some git commands takes options that are only used for plumbing or that
+	Some git commands take options that are only used for plumbing or that
 	are deprecated, and such options are hidden from the default usage. This
-	switch gives the full list of options.
+	option gives the full list of options.
 
 
 Negating options
 ~~~~~~~~~~~~~~~~
-Another things to keep in mind is that long options can be negated. For
+Boolean options with long option names can be negated by prefixing `"--no-"`. For
 example, `"git branch"` has the option `"--track"` which is 'on' by default. You
 can use `"--no-track"` to override that behaviour. The same goes for `"--color"`
 and `"--no-color"`.

@@ -74,10 +83,10 @@ options. This means that you can for example use `"git rm -rf"` or
 `"git clean -fdx"`.
 
 
-Separating argument from the switch
+Separating argument from the option
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Also for option switches that take a mandatory argument, you can separate it
-from the switch. That means that all the following uses are correct:
+You can write the mandatory option parameter to an option as a separate
+word on the command line.  That means that all the following uses work:
 
 ----------------------------
 $ git foo --long-opt=Arg

@@ -86,7 +95,7 @@ $ git foo -oArg
 $ git foo -o Arg
 ----------------------------
 
-However, this is *NOT* possible for switches with an optionnal value, where the
+However, this is *NOT* allowed for switches with an optionnal value, where the
 'sticked' form must be used:
 ----------------------------
 $ git describe --abbrev HEAD     # correct

@@ -1172,6 +1172,7 @@ check-docs::
 		documented,gitattributes | \
 		documented,gitignore | \
 		documented,gitmodules | \
+		documented,gitcli | \
 		documented,git-tools | \
 		sentinel,not,matching,is,ok ) continue ;; \
 		esac; \