[PATCH] Improve documentation for git-sh-setup.

[Yann Dirson <ydirson@altern.org>]

Signed-off-by: Yann Dirson <ydirson@altern.org>
Cc: Pierre Habouzit <madcoder@debian.org>
---

 Documentation/git-sh-setup.txt |   23 ++++++++++++++++++-----
 1 files changed, 18 insertions(+), 5 deletions(-)


diff --git a/Documentation/git-sh-setup.txt b/Documentation/git-sh-setup.txt
index 16b8b75..75e6846 100644
--- a/Documentation/git-sh-setup.txt
+++ b/Documentation/git-sh-setup.txt
@@ -19,12 +19,25 @@ Porcelain-ish scripts and/or are writing new ones.
 The `git-sh-setup` scriptlet is designed to be sourced (using
 `.`) by other shell scripts to set up some variables pointing at
 the normal git directories and a few helper shell functions.
+It also provides help messages, and some amount of command-line
+parsing.
 
-Before sourcing it, your script should set up a few variables;
-`USAGE` (and `LONG_USAGE`, if any) is used to define message
-given by `usage()` shell function.  `SUBDIRECTORY_OK` can be set
-if the script can run from a subdirectory of the working tree
-(some commands do not).
+Before sourcing it, your script should set up a few variables.
+
+`OPTIONS_SPEC` allows to declare the options so that the command-line
+can be pre-processed, and the usage message autogenerated.  It must
+follow the rules which apply to arguments to `git rev-parse
+--parseopt`.  If you need `git-rev-parse --parseopt` to keep the `--`
+the user may have passed to your command, you should also set
+`OPTIONS_KEEPDASHDASH` to a non empty value.
+
+If the constraints imposed by the use of `git rev-parse` do not fit
+for a particular tool, `USAGE` (and `LONG_USAGE`, if any) can be used
+to define message given by `usage()` shell function; no command-line
+pre-processing occurs, the script has entire control over it.
+
+`SUBDIRECTORY_OK` can be set if the script can run from a subdirectory
+of the working tree (some commands do not).
 
 The scriptlet sets `GIT_DIR` and `GIT_OBJECT_DIRECTORY` shell
 variables, but does *not* export them to the environment.