Some misc Documentation patches

Some misc Documentation patches

[Frank Lichtenheld]

The result of me playing around with git format-patch and git-am.

builtin-log.c: Fix typo in comment
Found while searching for the omnious --mbox option

Documentation: format-patch has no --mbox option
Replace --mbox with --stdout. Probably needs some more
thought to really improve the documentation

git-am: Clean up the asciidoc documentation
Fixing some things that annoyed me while reading the man page
and some things that I found while fixing the former.
If I should split that in more than one patch, please say so.

 Documentation/git-am.txt        |   38 ++++++++++++++++++++------------------
 Documentation/git-applymbox.txt |    2 +-
 Documentation/git-mailinfo.txt  |    3 +--
 builtin-log.c                   |    3 +--
 4 files changed, 23 insertions(+), 23 deletions(-)

[PATCH] builtin-log.c: Fix typo in comment

[Frank Lichtenheld]

s/fmt-patch/format-patch/

Signed-off-by: Frank Lichtenheld <frank@lichtenheld.de>
---
 builtin-log.c |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)

diff --git a/builtin-log.c b/builtin-log.c
index 38bf52f..3744712 100644
--- a/builtin-log.c
+++ b/builtin-log.c
@@ -454,7 +454,7 @@ int cmd_format_patch(int argc, const char **argv, const char *prefix)
 
 	/*
 	 * Parse the arguments before setup_revisions(), or something
-	 * like "git fmt-patch -o a123 HEAD^.." may fail; a123 is
+	 * like "git format-patch -o a123 HEAD^.." may fail; a123 is
 	 * possibly a valid SHA1.
 	 */
 	for (i = 1, j = 1; i < argc; i++) {
-- 
1.5.1.4

[PATCH] Documentation: format-patch has no --mbox option

[Frank Lichtenheld]

git-applymbox and git-mailinfo refer to a --mbox
option of git-format-patch. But there is no such
option AFAICT. mbox output can produced with
format-patch --stdout.

This patch only replaces --mbox with --stdout.
Some further explanation and/or format-patch
arguments (e.g. -k) might be needed.

Signed-off-by: Frank Lichtenheld <frank@lichtenheld.de>
---
 Documentation/git-applymbox.txt |    2 +-
 Documentation/git-mailinfo.txt  |    2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-applymbox.txt b/Documentation/git-applymbox.txt
index 3bc92d8..761ca3e 100644
--- a/Documentation/git-applymbox.txt
+++ b/Documentation/git-applymbox.txt
@@ -31,7 +31,7 @@ OPTIONS
 	whitespaces, (3) '[' up to ']', typically '[PATCH]', and
 	then prepends "[PATCH] ".  This flag forbids this
 	munging, and is most useful when used to read back 'git
-	format-patch --mbox' output.
+	format-patch --stdout' output.
 
 -m::
 	Patches are applied with `git-apply` command, and unless
diff --git a/Documentation/git-mailinfo.txt b/Documentation/git-mailinfo.txt
index ba18133..d49eee9 100644
--- a/Documentation/git-mailinfo.txt
+++ b/Documentation/git-mailinfo.txt
@@ -30,7 +30,7 @@ OPTIONS
 	whitespaces, (3) '[' up to ']', typically '[PATCH]', and
 	then prepends "[PATCH] ".  This flag forbids this
 	munging, and is most useful when used to read back 'git
-	format-patch --mbox' output.
+	format-patch --stdout' output.
 
 -u::
 	The commit log message, author name and author email are
-- 
1.5.1.4

Re: [PATCH] Documentation: format-patch has no --mbox option

[Junio C Hamano]

Frank Lichtenheld <frank@lichtenheld.de> writes:

> git-applymbox and git-mailinfo refer to a --mbox
> option of git-format-patch. But there is no such
> option AFAICT. mbox output can produced with
> format-patch --stdout.
>
> This patch only replaces --mbox with --stdout.
> Some further explanation and/or format-patch
> arguments (e.g. -k) might be needed.

I would agree.  "Reads single mbox with one or more patches in
it, without munging the subject line" is what it really does, so
we obviously mean "--stdout -k >mbox" here.

Re: [PATCH] Documentation: format-patch has no --mbox option

[Junio C Hamano]

Junio C Hamano <junkio@cox.net> writes:

> Frank Lichtenheld <frank@lichtenheld.de> writes:
>
>> git-applymbox and git-mailinfo refer to a --mbox
>> option of git-format-patch. But there is no such
>> option AFAICT. mbox output can produced with
>> format-patch --stdout.
>>
>> This patch only replaces --mbox with --stdout.
>> Some further explanation and/or format-patch
>> arguments (e.g. -k) might be needed.
>
> I would agree.  "Reads single mbox with one or more patches in
> it, without munging the subject line" is what it really does, so
> we obviously mean "--stdout -k >mbox" here.

Come to think of it, "no munging of Subject lines" is orthogonal
to the number of patches in a file, so it should say that the
option corresponds to -k in format-patch, I think.

So, I think we can just do s/--mbox/-k/, instead of s/--mbox/--stdout/
which is what you did.

[PATCH] git-am: Clean up the asciidoc documentation

[Frank Lichtenheld]

Add --keep to synopsis.
The synopsys used a mix of tabs and spaces, unified
to use only spaces.

Shuffle options around in synopsys and description
for grouping them logically.

Add more gitlink references to other commands.

Various grammatical fixes and improvements.

Signed-off-by: Frank Lichtenheld <frank@lichtenheld.de>
---
 Documentation/git-am.txt |   37 ++++++++++++++++++++-----------------
 1 files changed, 20 insertions(+), 17 deletions(-)

diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt
index f0405a3..0bc9123 100644
--- a/Documentation/git-am.txt
+++ b/Documentation/git-am.txt
@@ -9,9 +9,10 @@ git-am - Apply a series of patches from a mailbox
 SYNOPSIS
 --------
 [verse]
-'git-am' [--signoff] [--dotest=<dir>] [--utf8 | --no-utf8] [--binary] [--3way]
-         [--interactive] [--whitespace=<option>] [-C<n>] [-p<n>]
-	 <mbox>...
+'git-am' [--signoff] [--dotest=<dir>] [--keep] [--utf8 | --no-utf8]
+         [--3way] [--interactive] [--binary]
+         [--whitespace=<option>] [-C<n>] [-p<n>]
+         <mbox>...
 'git-am' [--skip | --resolved]
 
 DESCRIPTION
@@ -40,7 +41,7 @@ OPTIONS
 -u, --utf8::
 	Pass `-u` flag to `git-mailinfo` (see gitlink:git-mailinfo[1]).
 	The proposed commit log message taken from the e-mail
-	are re-coded into UTF-8 encoding (configuration variable
+	is re-coded into UTF-8 encoding (configuration variable
 	`i18n.commitencoding` can be used to specify project's
 	preferred encoding if it is not UTF-8).
 +
@@ -51,30 +52,32 @@ default.   You could use `--no-utf8` to override this.
 	Pass `-n` flag to `git-mailinfo` (see
 	gitlink:git-mailinfo[1]).
 
--b, --binary::
-	Pass `--allow-binary-replacement` flag to `git-apply`
-	(see gitlink:git-apply[1]).
-
 -3, --3way::
 	When the patch does not apply cleanly, fall back on
 	3-way merge, if the patch records the identity of blobs
 	it is supposed to apply to, and we have those blobs
-	locally.
+	available locally.
 
---skip::
-	Skip the current patch.  This is only meaningful when
-	restarting an aborted patch.
+-b, --binary::
+	Pass `--allow-binary-replacement` flag to `git-apply`
+	(see gitlink:git-apply[1]).
 
 --whitespace=<option>::
-	This flag is passed to the `git-apply` program that applies
+	This flag is passed to the `git-apply` (see gitlink:git-apply[1])
+	program that applies
 	the patch.
 
 -C<n>, -p<n>::
-	These flags are passed to the `git-apply` program that applies
+	These flags are passed to the `git-apply` (see gitlink:git-apply[1])
+	program that applies
 	the patch.
 
 -i, --interactive::
-	Run interactively, just like git-applymbox.
+	Run interactively, just like `git-applymbox` (see gitlink:git-applymbox[1]).
+
+--skip::
+	Skip the current patch.  This is only meaningful when
+	restarting an aborted patch.
 
 -r, --resolved::
 	After a patch failure (e.g. attempting to apply
@@ -99,7 +102,7 @@ message, and commit author time is taken from the "Date: " line
 of the message.  The "Subject: " line is used as the title of
 the commit, after stripping common prefix "[PATCH <anything>]".
 It is supposed to describe what the commit is about concisely as
-a one line text.
+an one line text.
 
 The body of the message (iow, after a blank line that terminates
 RFC2822 headers) can begin with "Subject: " and "From: " lines
@@ -126,7 +129,7 @@ to crunch.  Upon seeing the first patch that does not apply, it
 aborts in the middle, just like 'git-applymbox' does.  You can
 recover from this in one of two ways:
 
-. skip the current one by re-running the command with '--skip'
+. skip the current patch by re-running the command with '--skip'
   option.
 
 . hand resolve the conflict in the working directory, and update
-- 
1.5.1.4

Re: [PATCH] git-am: Clean up the asciidoc documentation

[Junio C Hamano]

Frank Lichtenheld <frank@lichtenheld.de> writes:

>  -i, --interactive::
> -	Run interactively, just like git-applymbox.
> +	Run interactively, just like `git-applymbox` (see gitlink:git-applymbox[1]).

This is an unclear description from the original, but I think we
should say just like `git-applybox -i`, or drop this altogether.

> @@ -99,7 +102,7 @@ message, and commit author time is taken from the "Date: " line
>  of the message.  The "Subject: " line is used as the title of
>  the commit, after stripping common prefix "[PATCH <anything>]".
>  It is supposed to describe what the commit is about concisely as
> -a one line text.
> +an one line text.

I think 'one' does not begin with a vowel.

Other than that, I would agree everything in your update is a
clear improvement.

Re: [PATCH] git-am: Clean up the asciidoc documentation

[Frank Lichtenheld]

On Mon, May 14, 2007 at 05:01:38PM -0700, Junio C Hamano wrote:
> Frank Lichtenheld <frank@lichtenheld.de> writes:
> 
> >  -i, --interactive::
> > -	Run interactively, just like git-applymbox.
> > +	Run interactively, just like `git-applymbox` (see gitlink:git-applymbox[1]).
> 
> This is an unclear description from the original, but I think we
> should say just like `git-applybox -i`, or drop this altogether.

Hmm, your comment doesn't make any sense to me, because applymbox has
no -i option.

Gruesse,
-- 
Frank Lichtenheld <frank@lichtenheld.de>
www: http://www.djpig.de/

Re: [PATCH] git-am: Clean up the asciidoc documentation

[Junio C Hamano]

Frank Lichtenheld <frank@lichtenheld.de> writes:

> On Mon, May 14, 2007 at 05:01:38PM -0700, Junio C Hamano wrote:
>> Frank Lichtenheld <frank@lichtenheld.de> writes:
>> 
>> >  -i, --interactive::
>> > -	Run interactively, just like git-applymbox.
>> > +	Run interactively, just like `git-applymbox` (see gitlink:git-applymbox[1]).
>> 
>> This is an unclear description from the original, but I think we
>> should say just like `git-applybox -i`, or drop this altogether.
>
> Hmm, your comment doesn't make any sense to me, because applymbox has
> no -i option.

Ah, my braino.  Thanks.

We are not encouraging applymbox to new users anyway, so I'd
just drop the whole ", just like" business.