Re: [PATCH] usage: do not insist that standard input must come from a file

[Junio C Hamano <gitster@pobox.com>]

Here is what I prepared based on your review in an interdiff form.
A few points to note:

 * Stole the "fmt-merge-msg" example verbatim ;-)

 * The description of "show-ref --exclude" mode should be much
   clearer now.

Thanks.

diff --git a/Documentation/git-check-attr.txt b/Documentation/git-check-attr.txt
index 07aacf2..aa3b2bf 100644
--- a/Documentation/git-check-attr.txt
+++ b/Documentation/git-check-attr.txt
@@ -28,7 +28,8 @@ OPTIONS
 	Consider `.gitattributes` in the index only, ignoring the working tree.
 
 --stdin::
-	Read pathnames from stdin instead of from the command-line.
+	Read pathnames from the standard input, one per line,
+	instead of from the command-line.
 
 -z::
 	The output format is modified to be machine-parseable.
diff --git a/Documentation/git-check-ignore.txt b/Documentation/git-check-ignore.txt
index 149b166..59531ab 100644
--- a/Documentation/git-check-ignore.txt
+++ b/Documentation/git-check-ignore.txt
@@ -35,7 +35,8 @@ OPTIONS
 	for each given pathname.
 
 --stdin::
-	Read file names from stdin instead of from the command-line.
+	Read pathnames from the standard input, one per line,
+	instead of from the command-line.
 
 -z::
 	The output format is modified to be machine-parseable (see
diff --git a/Documentation/git-fmt-merge-msg.txt b/Documentation/git-fmt-merge-msg.txt
index 9be6df3..6526b17 100644
--- a/Documentation/git-fmt-merge-msg.txt
+++ b/Documentation/git-fmt-merge-msg.txt
@@ -57,6 +57,18 @@ merge.summary::
 	Synonym to `merge.log`; this is deprecated and will be removed in
 	the future.
 
+EXAMPLE
+-------
+
+--
+$ git fetch origin master
+$ git fmt-merge-msg --log <$GIT_DIR/FETCH_HEAD
+--
+
+Print a log message describing a merge of the "master" branch from
+the "origin" remote.
+
+
 SEE ALSO
 --------
 linkgit:git-merge[1]
diff --git a/Documentation/git-get-tar-commit-id.txt b/Documentation/git-get-tar-commit-id.txt
index 51804b0..ac44d85 100644
--- a/Documentation/git-get-tar-commit-id.txt
+++ b/Documentation/git-get-tar-commit-id.txt
@@ -15,10 +15,10 @@ SYNOPSIS
 DESCRIPTION
 -----------
 
-Read an archive created by 'git archive' from the standard input and
-extracts the commit ID stored in it.  It reads only the first 1024
-bytes of input, thus its runtime is not influenced by the size of
-the archive very much.
+Read a tar archive created by 'git archive' from the standard input
+and extract the commit ID stored in it.  It reads only the first
+1024 bytes of input, thus its runtime is not influenced by the size
+of the tar archive very much.
 
 If no commit ID is found, 'git get-tar-commit-id' quietly exists with a
 return code of 1.  This can happen if the archive had not been created
diff --git a/Documentation/git-hash-object.txt b/Documentation/git-hash-object.txt
index 45e5ece..814e744 100644
--- a/Documentation/git-hash-object.txt
+++ b/Documentation/git-hash-object.txt
@@ -35,7 +35,8 @@ OPTIONS
 	Read the object from standard input instead of from a file.
 
 --stdin-paths::
-	Read file names from stdin instead of from the command-line.
+	Read file names from the standard input, one per line, instead
+	of from the command-line.
 
 --path::
 	Hash object as it were located at the given path. The location of
diff --git a/Documentation/git-mktag.txt b/Documentation/git-mktag.txt
index f4cc202..fa6a756 100644
--- a/Documentation/git-mktag.txt
+++ b/Documentation/git-mktag.txt
@@ -20,8 +20,8 @@ The output is the new tag's <object> identifier.
 
 Tag Format
 ----------
-A tag signature file, to be fed from the standard input, has a
-very simple fixed format: four lines of
+A tag signature file, to be fed to this command's standard input,
+has a very simple fixed format: four lines of
 
   object <sha1>
   type <typename>
diff --git a/Documentation/git-patch-id.txt b/Documentation/git-patch-id.txt
index 7816479..cf71fba 100644
--- a/Documentation/git-patch-id.txt
+++ b/Documentation/git-patch-id.txt
@@ -12,7 +12,7 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-Read a patch from the standard input, and compute the patch ID for it.
+Read a patch from the standard input and compute the patch ID for it.
 
 A "patch ID" is nothing but a sum of SHA-1 of the file diffs associated with a
 patch, with whitespace and line numbers ignored.  As such, it's "reasonably
diff --git a/Documentation/git-show-index.txt b/Documentation/git-show-index.txt
index b3e7488..a8a9509 100644
--- a/Documentation/git-show-index.txt
+++ b/Documentation/git-show-index.txt
@@ -14,7 +14,7 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-Read an idx file for packed Git archive created with
+Read the idx file for a Git packfile created with
 'git pack-objects' command from the standard input, and
 dump its contents.
 
diff --git a/Documentation/git-show-ref.txt b/Documentation/git-show-ref.txt
index 2c08b08..7b74340 100644
--- a/Documentation/git-show-ref.txt
+++ b/Documentation/git-show-ref.txt
@@ -23,8 +23,9 @@ particular ref exists.
 
 By default, shows the tags, heads, and remote refs.
 
-The --exclude-existing form is a filter that does the inverse, it shows the
-refs from stdin that don't exist in the local repository.
+The --exclude-existing form is a filter that does the inverse.  It reads
+refs from stdin, one ref per line, and shows those that don't exist in
+the local repository.
 
 Use of this utility is encouraged in favor of directly accessing files under
 the `.git` directory.