Re: [PATCH 2/2] parseopt: Add a gitcli(5) man page.

From: Wincent Colaiuta <win@wincent.com>
Date: Dec 13, 2007, 11:04 UTC
Message-ID: <A78DF383-1BD5-4AED-9DE8-60B8E96E54B5@wincent.com>
In-Reply-To: <20071213102724.GE12398@artemis.madism.org>

El 13/12/2007, a las 11:27, Pierre Habouzit escribió:

> This page should hold every information about the git ways to parse  
> command
> lines, and best practices to be used for scripting.

Some feedback from a native English speaker follows...

Show 7 quoted lines

> @@ -0,0 +1,104 @@
> +gitcli(5)
> +=========
> +
> +NAME
> +----
> +gitcli - git command line interface and its usual conventions

"git command line interface and conventions" sounds better; the "usual" is redundant.

Or did you mean "*usage* conventions"? If that is the case, "git command line interface and usage" is better, but just "git command line interface" is enough.

Show 5 quoted lines

> +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:

Suggest "how to use the git CLI".

> + * it's preferred to use the non dashed form of git commands, which  
> means that
> +   you should prefer `"git foo"` to `"git-foo"`.

"non-dashed", and in any case, this could be more concise. How about:

* the non-dashed form of git commands is preferred; use `"git foo"`  
rather than
  `"git-foo"`

> + * splitting short option switches in separate atoms (prefer `"git  
> foo -a -b"`
> +   to `"git foo -ab"`, the latter may not even work).

"*split* short option switches *into* separate atoms"

And the comma before "the latter may not even work" should be a semi- colon.

Show 7 quoted lines

> + * 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.

Again this could be more concise. Instead of:

	"which means that you must prefer .... to ..."

you could just say:

	"use ... instead of ..."

Show 7 quoted lines

> +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

How about:

"From git 1.5.4 onwards, many git commands come with an enhanced option parser..."

Show 5 quoted lines

> +Magic Options
> +~~~~~~~~~~~~~
> +Commands which have the enhanced option parser activated all  
> understand a
> +couple of magic command line switches:

"Commands which use the enhanced option parser all understand..."

> +
> +-h::
> +	gives a pretty printed usage of the command.

"pretty-printed"

Show 6 quoted lines

> +--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.

"Some git commands *take* options that are deprecated or used only *by* plumbing"

And:

"such options are *not included in* the default usage" ("hidden from" sounds awkward).

> +Negating options
> +~~~~~~~~~~~~~~~~
> +Another things to keep in mind is that long options can be negated.

"Another *thing*"

But you could replace the whole sentence with just:

"Long options can be negated."

> +Separating argument from the switch
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

"Separating *the* argument from the switch"

Or if you prefer

"Separating *arguments* from the *switches*"

> +However, this is *NOT* possible for switches with an optionnal  
> value, where the
> +'sticked' form must be used:

Typo: "optional"

Cheers, Wincent