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

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

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

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

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

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

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

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