From: Ralf Wildenhues <ralf.wildenhues@gmx.de>
Date: Sun, 04 Nov 2007 11:29:31 GMT
Subject: Re: [PATCH 01/10] Add a parseopt mode to git-rev-parse to bring parse-options to shell scripts.
Message-ID: <20071104112931.GB2119@ins.uni-bonn.de>
In-Reply-To: <1194172262-1563-2-git-send-email-madcoder@debian.org>

Hello Pierre,

A couple of language nits:

* Pierre Habouzit wrote on Sun, Nov 04, 2007 at 11:30:53AM CET:
> +PARSEOPT
> +--------
> +
> +In `--parseopt` mode, `git-rev-parse` helps massaging options to bring to shell
> +scripts the same facilities C builtins have. It works as an option normalizer
> +(e.g. splits single switches aggregate values), a bit like `getopt(1)` does.
> +
> +It takes on the standard input the specification of the options to parse and
> +understand, and echoes on the standard ouput a line suitable for `sh(1)` `eval`
> +to replace the arguments with normalized ones.  In case of error, it ouputs

s/ouputs/outputs/

> +usage on the standard error stream, and exits with code 129.
> +
> +Input Format
> +~~~~~~~~~~~~
> +
> +`git-ref-parse --parseopt` input format is fully text based. It has two parts,

s/^/The /
s/git-ref-parse/git-rev-parse/

> +separated by a line that contains only `--`. The lines before (should be more
> +than one) are used for the usage. The lines after describe the options.

I would write
  s/before/& the `--`/
  s/after/& the `--`/

or maybe write "separator" instead of `--`.

[...]
> +`<opt_spec>`::
> +	its format is the short option character, then the long option name
> +        separated by a comma. Both parts are not required, though at least one
> +        is necessary. `h,help`, `dry-run` and `f` are all three correct
> +        `<opt_spec>`.
> +
> +`<arg_spec>`::
> +	an `<arg_spec>` tells the option parser if the option has an argument
> +        (`=`), an optionnal one (`?` though its use is discouraged) or none

s/optionnal/optional/

> +        (no `<arg_spec>` in that case).
> +
> +The rest of the line after as many spaces up to the ending line feed is used
> +as the help associated to the option.

I'd write (in case that is technically correct):
  After following white space, the rest of the line after is used as the
  help associated to the option.

> +Blank lines are ignored, and lines that don't match this specification are used
> +as option group headers (start the line with a space to purposely create such
> +lines).

I'd write:
  ... to create such lines on purpose.

> +Example
> +~~~~~~~
> +
> +------------
> +OPTS_SPEC="\
> +some-command [options] <args>...
> +
> +some-command does foo and bar !

Please no white space before "!".

> +--
> +h,help    show the help
> +
> +foo       some nifty option --foo
> +bar=      some cool option --bar with an argument
> +
> +  An option group Header
> +C?        option C with an optionnal argument"

s/optionnal/optional/

Cheers,
Ralf