[PATCH 0/8] Doc updates to config, format-patch, show-branch

[PATCH 0/8] Doc updates to config, format-patch, show-branch

[Stephen Boyd]

I've tried to order these from least to most controversial.

The first 3 are small fixups. The fourth patch is a quoting fixup. The
fifth patch is a patch I sent a few weeks ago which flew under the radar.
The last 3 patches are some updates to the config.txt documentation.
I've split them up into seperate patches so they can easily be left out
if not wanted.

Stephen Boyd (8):
  config.txt: remove pointer to SubmittingPatches
  config.txt: add missing format.{subjectprefix,cc,attach} variables
  Documentation: use lowercase for shallow and deep threading
  git-show-branch.txt: cleanup example description
  git-format-patch.txt: general rewordings and cleanups
  config.txt: add missing 'the's and make words plural
  config.txt: clarify sentences in the configuration and syntax sections
  config.txt: Make configuration paragraph more consistent

 Documentation/config.txt           |   68 +++++++++++++++++++++--------------
 Documentation/git-format-patch.txt |   42 +++++++++++-----------
 Documentation/git-show-branch.txt  |    7 ++--
 3 files changed, 66 insertions(+), 51 deletions(-)

[PATCH 1/8] config.txt: remove pointer to SubmittingPatches

[Stephen Boyd]

SubmittingPatches exists in the git source documentation for developers
of git and is not included in the man/html page distributions.

Signed-off-by: Stephen Boyd <bebarino@gmail.com>
---
 Documentation/config.txt |    1 -
 1 files changed, 0 insertions(+), 1 deletions(-)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index 35056e1..fb7adfa 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -743,7 +743,6 @@ format.signoff::
     format-patch by default. *Note:* Adding the Signed-off-by: line to a
     patch should be a conscious act and means that you certify you have
     the rights to submit this work under the same open source license.
-    Please see the 'SubmittingPatches' document for further discussion.
 
 gc.aggressiveWindow::
 	The window size parameter used in the delta compression
-- 
1.6.2.3

[PATCH 2/8] config.txt: add missing format.{subjectprefix,cc,attach} variables

[Stephen Boyd]

Signed-off-by: Stephen Boyd <bebarino@gmail.com>
---
 Documentation/config.txt |   15 +++++++++++++++
 1 files changed, 15 insertions(+), 0 deletions(-)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index fb7adfa..a8b68e2 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -707,6 +707,13 @@ fetch.unpackLimit::
 	especially on slow filesystems.  If not set, the value of
 	`transfer.unpackLimit` is used instead.
 
+format.attach::
+	Enable multipart/mixed attachments as the default for
+	'format-patch'.  The value can also be a double quoted string
+	which will enable attachments as the default and set the
+	value as the boundary.  See the --attach option in
+	linkgit:git-format-patch[1].
+
 format.numbered::
 	A boolean which can enable or disable sequence numbers in patch
 	subjects.  It defaults to "auto" which enables it only if there
@@ -718,6 +725,14 @@ format.headers::
 	Additional email headers to include in a patch to be submitted
 	by mail.  See linkgit:git-format-patch[1].
 
+format.cc::
+	Additional "Cc:" headers to include in a patch to be submitted
+	by mail.  See the --cc option in linkgit:git-format-patch[1].
+
+format.subjectprefix::
+	The default for format-patch is to output files with the '[PATCH]'
+	subject prefix. Use this variable to change that prefix.
+
 format.suffix::
 	The default for format-patch is to output files with the suffix
 	`.patch`. Use this variable to change that suffix (make sure to
-- 
1.6.2.3

[PATCH 3/8] Documentation: use lowercase for shallow and deep threading

[Stephen Boyd]

Even when a sentence is started with 'shallow' or 'deep' use the
lowercase version to maintain consistency.

Signed-off-by: Stephen Boyd <bebarino@gmail.com>
---
 Documentation/config.txt           |    4 ++--
 Documentation/git-format-patch.txt |    4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index a8b68e2..cabac97 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -745,11 +745,11 @@ format.pretty::
 
 format.thread::
 	The default threading style for 'git-format-patch'.  Can be
-	either a boolean value, `shallow` or `deep`.  'Shallow'
+	either a boolean value, `shallow` or `deep`.  `shallow`
 	threading makes every mail a reply to the head of the series,
 	where the head is chosen from the cover letter, the
 	`\--in-reply-to`, and the first patch mail, in this order.
-	'Deep' threading makes every mail a reply to the previous one.
+	`deep` threading makes every mail a reply to the previous one.
 	A true boolean value is the same as `shallow`, and a false
 	value disables threading.
 
diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt
index 5eddca9..4a43c64 100644
--- a/Documentation/git-format-patch.txt
+++ b/Documentation/git-format-patch.txt
@@ -128,9 +128,9 @@ include::diff-options.txt[]
 	the Message-Id header to reference.
 +
 The optional <style> argument can be either `shallow` or `deep`.
-'Shallow' threading makes every mail a reply to the head of the
+'shallow' threading makes every mail a reply to the head of the
 series, where the head is chosen from the cover letter, the
-`\--in-reply-to`, and the first patch mail, in this order.  'Deep'
+`\--in-reply-to`, and the first patch mail, in this order.  'deep'
 threading makes every mail a reply to the previous one.  If not
 specified, defaults to the 'format.thread' configuration, or `shallow`
 if that is not set.
-- 
1.6.2.3

[PATCH 4/8] git-show-branch.txt: cleanup example description

[Stephen Boyd]

Add a missing quote and properly escape the ' character so docs don't
look odd. Add 'the' to make some sentences more gramatically correct.

Signed-off-by: Stephen Boyd <bebarino@gmail.com>
---
 Documentation/git-show-branch.txt |    7 ++++---
 1 files changed, 4 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-show-branch.txt b/Documentation/git-show-branch.txt
index 7e9ff37..51a4e9d 100644
--- a/Documentation/git-show-branch.txt
+++ b/Documentation/git-show-branch.txt
@@ -148,9 +148,10 @@ $ git show-branch master fixes mhf
 ------------------------------------------------
 
 These three branches all forked from a common commit, [master],
-whose commit message is "Add 'git show-branch'.  "fixes" branch
-adds one commit 'Introduce "reset type"'.  "mhf" branch has many
-other commits.  The current branch is "master".
+whose commit message is "Add \'git show-branch\'". The "fixes"
+branch adds one commit "Introduce "reset type" flag to "git reset"".
+The "mhf" branch adds many other commits. The current branch
+is "master".
 
 
 EXAMPLE
-- 
1.6.2.3

[PATCH 5/8] git-format-patch.txt: general rewordings and cleanups

[Stephen Boyd]

Clarify --no-binary description using some words from the original
commit 37c22a4b (add --no-binary, 2008-05-9). Cleanup --suffix
description. Add --thread style option to synopsis and reorganize it a
bit. Clarify renaming patches example and the configuration paragraph.

Signed-off-by: Stephen Boyd <bebarino@gmail.com>
---
 Documentation/git-format-patch.txt |   38 ++++++++++++++++++------------------
 1 files changed, 19 insertions(+), 19 deletions(-)

diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt
index 4a43c64..5ac9e33 100644
--- a/Documentation/git-format-patch.txt
+++ b/Documentation/git-format-patch.txt
@@ -9,10 +9,10 @@ git-format-patch - Prepare patches for e-mail submission
 SYNOPSIS
 --------
 [verse]
-'git format-patch' [-k] [-o <dir> | --stdout] [--thread]
-		   [--attach[=<boundary>] | --inline[=<boundary>] |
-		     [--no-attach]]
-		   [-s | --signoff] [<common diff options>]
+'git format-patch' [-k] [(-o|--output-directory) <dir> | --stdout]
+		   [--thread[=<style>]]
+		   [(--attach|--inline)[=<boundary>] | --no-attach]
+		   [-s | --signoff]
 		   [-n | --numbered | -N | --no-numbered]
 		   [--start-number <n>] [--numbered-files]
 		   [--in-reply-to=Message-Id] [--suffix=.<sfx>]
@@ -20,6 +20,7 @@ SYNOPSIS
 		   [--subject-prefix=Subject-Prefix]
 		   [--cc=<email>]
 		   [--cover-letter]
+		   [<common diff options>]
 		   [ <since> | <revision range> ]
 
 DESCRIPTION
@@ -170,18 +171,17 @@ if that is not set.
 --suffix=.<sfx>::
 	Instead of using `.patch` as the suffix for generated
 	filenames, use specified suffix.  A common alternative is
-	`--suffix=.txt`.
+	`--suffix=.txt`.  Leaving this empty will remove the `.patch`
+	suffix.
 +
-Note that you would need to include the leading dot `.` if you
-want a filename like `0001-description-of-my-change.patch`, and
-the first letter does not have to be a dot.  Leaving it empty would
-not add any suffix.
+Note the leading character does not have to be a dot; for example, you
+can use `--suffix=-patch` to get `0001-description-of-my-change-patch`.
 
 --no-binary::
-	Don't output contents of changes in binary files, just take note
-	that they differ.  Note that this disable the patch to be properly
-	applied.  By default the contents of changes in those files are
-	encoded in the patch.
+	Do not output contents of changes in binary files, instead
+	display a notice that those files changed.  Patches generated
+	using this option cannot be applied properly, but they are
+	still useful for code review.
 
 --root::
 	Treat the revision argument as a <revision range>, even if it
@@ -192,10 +192,10 @@ not add any suffix.
 
 CONFIGURATION
 -------------
-You can specify extra mail header lines to be added to each message
-in the repository configuration, new defaults for the subject prefix
-and file suffix, control attachments, and number patches when outputting
-more than one.
+You can specify extra mail header lines to be added to each message,
+defaults for the subject prefix and file suffix, number patches when
+outputting more than one patch, add "Cc:" headers, configure attachments,
+and signoff patches with configuration variables.
 
 ------------
 [format]
@@ -243,8 +243,8 @@ $ git format-patch -M -B origin
 +
 Additionally, it detects and handles renames and complete rewrites
 intelligently to produce a renaming patch.  A renaming patch reduces
-the amount of text output, and generally makes it easier to review it.
-Note that the "patch" program does not understand renaming patches, so
+the amount of text output, and generally makes it easier to review.
+Note that non-git "patch" programs won't understand renaming patches, so
 use it only when you know the recipient uses git to apply your patch.
 
 * Extract three topmost commits from the current branch and format them
-- 
1.6.2.3

[PATCH 6/8] config.txt: add missing 'the's and make words plural

[Stephen Boyd]

Signed-off-by: Stephen Boyd <bebarino@gmail.com>
---
 Documentation/config.txt |   34 +++++++++++++++++-----------------
 1 files changed, 17 insertions(+), 17 deletions(-)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index cabac97..1f17e7a 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -2,10 +2,10 @@ CONFIGURATION FILE
 ------------------
 
 The git configuration file contains a number of variables that affect
-the git command's behavior. `.git/config` file for each repository
+the git command's behavior. The `.git/config` file in each repository
 is used to store the information for that repository, and
-`$HOME/.gitconfig` is used to store per user information to give
-fallback values for `.git/config` file. The file `/etc/gitconfig`
+`$HOME/.gitconfig` is used to store per user information as
+fallback values for the `.git/config` file. The file `/etc/gitconfig`
 can be used to store system-wide defaults.
 
 They can be used by both the git plumbing
@@ -26,28 +26,28 @@ The file consists of sections and variables.  A section begins with
 the name of the section in square brackets and continues until the next
 section begins.  Section names are not case sensitive.  Only alphanumeric
 characters, `-` and `.` are allowed in section names.  Each variable
-must belong to some section, which means that there must be section
-header before first setting of a variable.
+must belong to some section, which means that there must be a section
+header before the first setting of a variable.
 
 Sections can be further divided into subsections.  To begin a subsection
 put its name in double quotes, separated by space from the section name,
-in the section header, like in example below:
+in the section header, like in the example below:
 
 --------
 	[section "subsection"]
 
 --------
 
-Subsection names can contain any characters except newline (doublequote
+Subsection names can contain any character except newline (doublequote
 `"` and backslash have to be escaped as `\"` and `\\`,
-respectively) and are case sensitive.  Section header cannot span multiple
+respectively) and are case sensitive.  Section headers cannot span multiple
 lines.  Variables may belong directly to a section or to a given subsection.
 You can have `[section]` if you have `[section "subsection"]`, but you
 don't need to.
 
-There is also (case insensitive) alternative `[section.subsection]` syntax.
-In this syntax subsection names follow the same restrictions as for section
-name.
+There is also a case insensitive alternative `[section.subsection]` syntax.
+In this syntax, subsection names follow the same restrictions as for section
+names.
 
 All the other lines are recognized as setting variables, in the form
 'name = value'.  If there is no equal sign on the line, the entire line
@@ -66,10 +66,10 @@ converting value to the canonical form using '--bool' type specifier;
 'git-config' will ensure that the output is "true" or "false".
 
 String values may be entirely or partially enclosed in double quotes.
-You need to enclose variable value in double quotes if you want to
-preserve leading or trailing whitespace, or if variable value contains
-beginning of comment characters (if it contains '#' or ';').
-Double quote `"` and backslash `\` characters in variable value must
+You need to enclose variable values in double quotes if you want to
+preserve leading or trailing whitespace, or if the variable value contains
+comment characters (i.e. it contains '#' or ';').
+Double quote `"` and backslash `\` characters in variable values must
 be escaped: use `\"` for `"` and `\\` for `\`.
 
 The following escape sequences (beside `\"` and `\\`) are recognized:
@@ -77,10 +77,10 @@ The following escape sequences (beside `\"` and `\\`) are recognized:
 and `\b` for backspace (BS).  No other char escape sequence, nor octal
 char sequences are valid.
 
-Variable value ending in a `\` is continued on the next line in the
+Variable values ending in a `\` are continued on the next line in the
 customary UNIX fashion.
 
-Some variables may require special value format.
+Some variables may require a special value format.
 
 Example
 ~~~~~~~
-- 
1.6.2.3

[PATCH 7/8] config.txt: clarify sentences in the configuration and syntax sections

[Stephen Boyd]

Signed-off-by: Stephen Boyd <bebarino@gmail.com>
---
 Documentation/config.txt |   12 ++++++------
 1 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index 1f17e7a..acd9b31 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -8,9 +8,9 @@ is used to store the information for that repository, and
 fallback values for the `.git/config` file. The file `/etc/gitconfig`
 can be used to store system-wide defaults.
 
-They can be used by both the git plumbing
-and the porcelains. The variables are divided into sections, where
-in the fully qualified variable name the variable itself is the last
+The configuration variables are used by both the git plumbing
+and the porcelains. The variables are divided into sections, wherein
+the fully qualified variable name of the variable itself is the last
 dot-separated segment and the section name is everything before the last
 dot. The variable names are case-insensitive and only alphanumeric
 characters are allowed. Some variables may appear multiple times.
@@ -38,9 +38,9 @@ in the section header, like in the example below:
 
 --------
 
-Subsection names can contain any character except newline (doublequote
-`"` and backslash have to be escaped as `\"` and `\\`,
-respectively) and are case sensitive.  Section headers cannot span multiple
+Subsection names are case sensitive and can contain any characters except
+newline (doublequote `"` and backslash have to be escaped as `\"` and `\\`,
+respectively).  Section headers cannot span multiple
 lines.  Variables may belong directly to a section or to a given subsection.
 You can have `[section]` if you have `[section "subsection"]`, but you
 don't need to.
-- 
1.6.2.3

[PATCH 8/8] config.txt: Make configuration paragraph more consistent

[Stephen Boyd]

By renaming 'information' to 'configuration' we capture more clearly
what a configuration file holds.

Signed-off-by: Stephen Boyd <bebarino@gmail.com>
---
 Documentation/config.txt |    6 +++---
 1 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index acd9b31..0b5dad3 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -3,10 +3,10 @@ CONFIGURATION FILE
 
 The git configuration file contains a number of variables that affect
 the git command's behavior. The `.git/config` file in each repository
-is used to store the information for that repository, and
-`$HOME/.gitconfig` is used to store per user information as
+is used to store the configuration for that repository, and
+`$HOME/.gitconfig` is used to store a per-user configuration as
 fallback values for the `.git/config` file. The file `/etc/gitconfig`
-can be used to store system-wide defaults.
+can be used to store a system-wide default configuration.
 
 The configuration variables are used by both the git plumbing
 and the porcelains. The variables are divided into sections, wherein
-- 
1.6.2.3

Re: [PATCH 1/8] config.txt: remove pointer to SubmittingPatches

[Michael J Gruber]

Stephen Boyd venit, vidit, dixit 23.04.2009 11:37:
> SubmittingPatches exists in the git source documentation for developers
> of git and is not included in the man/html page distributions.
> 
> Signed-off-by: Stephen Boyd <bebarino@gmail.com>
> ---
>  Documentation/config.txt |    1 -
>  1 files changed, 0 insertions(+), 1 deletions(-)
> 
> diff --git a/Documentation/config.txt b/Documentation/config.txt
> index 35056e1..fb7adfa 100644
> --- a/Documentation/config.txt
> +++ b/Documentation/config.txt
> @@ -743,7 +743,6 @@ format.signoff::
>      format-patch by default. *Note:* Adding the Signed-off-by: line to a
>      patch should be a conscious act and means that you certify you have
>      the rights to submit this work under the same open source license.
> -    Please see the 'SubmittingPatches' document for further discussion.

Shouldn't we point to the source then? We're not talking about links
here, only references in the sense of referring to further reading.

>  
>  gc.aggressiveWindow::
>  	The window size parameter used in the delta compression

Re: [PATCH 5/8] git-format-patch.txt: general rewordings and cleanups

[Michael J Gruber]

Stephen Boyd venit, vidit, dixit 23.04.2009 11:37:
> Clarify --no-binary description using some words from the original
> commit 37c22a4b (add --no-binary, 2008-05-9). Cleanup --suffix
> description. Add --thread style option to synopsis and reorganize it a
> bit. Clarify renaming patches example and the configuration paragraph.
> 
> Signed-off-by: Stephen Boyd <bebarino@gmail.com>
> ---
>  Documentation/git-format-patch.txt |   38 ++++++++++++++++++------------------
>  1 files changed, 19 insertions(+), 19 deletions(-)
> 
> diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt
> index 4a43c64..5ac9e33 100644
> --- a/Documentation/git-format-patch.txt
> +++ b/Documentation/git-format-patch.txt
> @@ -9,10 +9,10 @@ git-format-patch - Prepare patches for e-mail submission
>  SYNOPSIS
>  --------
>  [verse]
> -'git format-patch' [-k] [-o <dir> | --stdout] [--thread]
> -		   [--attach[=<boundary>] | --inline[=<boundary>] |
> -		     [--no-attach]]
> -		   [-s | --signoff] [<common diff options>]
> +'git format-patch' [-k] [(-o|--output-directory) <dir> | --stdout]
> +		   [--thread[=<style>]]
> +		   [(--attach|--inline)[=<boundary>] | --no-attach]
> +		   [-s | --signoff]
>  		   [-n | --numbered | -N | --no-numbered]
>  		   [--start-number <n>] [--numbered-files]
>  		   [--in-reply-to=Message-Id] [--suffix=.<sfx>]
> @@ -20,6 +20,7 @@ SYNOPSIS
>  		   [--subject-prefix=Subject-Prefix]
>  		   [--cc=<email>]
>  		   [--cover-letter]
> +		   [<common diff options>]
>  		   [ <since> | <revision range> ]
>  
>  DESCRIPTION
> @@ -170,18 +171,17 @@ if that is not set.
>  --suffix=.<sfx>::
>  	Instead of using `.patch` as the suffix for generated
>  	filenames, use specified suffix.  A common alternative is
> -	`--suffix=.txt`.
> +	`--suffix=.txt`.  Leaving this empty will remove the `.patch`
> +	suffix.
>  +

Those asciidoc constructs in diff make me always wonder "Huh? A merge
diff -cc?"... It's fine, of course.

> -Note that you would need to include the leading dot `.` if you
> -want a filename like `0001-description-of-my-change.patch`, and
> -the first letter does not have to be a dot.  Leaving it empty would
> -not add any suffix.
> +Note the leading character does not have to be a dot; for example, you

Maybe "Note that the" sounds and reads better.

> +can use `--suffix=-patch` to get `0001-description-of-my-change-patch`.
>  
>  --no-binary::
> -	Don't output contents of changes in binary files, just take note
> -	that they differ.  Note that this disable the patch to be properly
> -	applied.  By default the contents of changes in those files are
> -	encoded in the patch.
> +	Do not output contents of changes in binary files, instead
> +	display a notice that those files changed.  Patches generated
> +	using this option cannot be applied properly, but they are
> +	still useful for code review.
>  
>  --root::
>  	Treat the revision argument as a <revision range>, even if it
> @@ -192,10 +192,10 @@ not add any suffix.
>  
>  CONFIGURATION
>  -------------
> -You can specify extra mail header lines to be added to each message
> -in the repository configuration, new defaults for the subject prefix
> -and file suffix, control attachments, and number patches when outputting
> -more than one.
> +You can specify extra mail header lines to be added to each message,
> +defaults for the subject prefix and file suffix, number patches when
> +outputting more than one patch, add "Cc:" headers, configure attachments,
> +and signoff patches with configuration variables.

"sign off"

>  
>  ------------
>  [format]
> @@ -243,8 +243,8 @@ $ git format-patch -M -B origin
>  +
>  Additionally, it detects and handles renames and complete rewrites
>  intelligently to produce a renaming patch.  A renaming patch reduces
> -the amount of text output, and generally makes it easier to review it.
> -Note that the "patch" program does not understand renaming patches, so
> +the amount of text output, and generally makes it easier to review.
> +Note that non-git "patch" programs won't understand renaming patches, so
>  use it only when you know the recipient uses git to apply your patch.
>  
>  * Extract three topmost commits from the current branch and format them

Looks nice overall, especially the ones I'm not replying to ;)

Michael

Re: [PATCH 1/8] config.txt: remove pointer to SubmittingPatches

[Stephen Boyd]

Michael J Gruber wrote:
> Stephen Boyd venit, vidit, dixit 23.04.2009 11:37:
>> SubmittingPatches exists in the git source documentation for developers
>> of git and is not included in the man/html page distributions.
>>
>> Signed-off-by: Stephen Boyd <bebarino@gmail.com>
>> ---
>>  Documentation/config.txt |    1 -
>>  1 files changed, 0 insertions(+), 1 deletions(-)
>>
>> diff --git a/Documentation/config.txt b/Documentation/config.txt
>> index 35056e1..fb7adfa 100644
>> --- a/Documentation/config.txt
>> +++ b/Documentation/config.txt
>> @@ -743,7 +743,6 @@ format.signoff::
>>      format-patch by default. *Note:* Adding the Signed-off-by: line to a
>>      patch should be a conscious act and means that you certify you have
>>      the rights to submit this work under the same open source license.
>> -    Please see the 'SubmittingPatches' document for further discussion.
>
> Shouldn't we point to the source then? We're not talking about links
> here, only references in the sense of referring to further reading.

I was thinking that a user isn't going to download the source for git so
they can read the SubmittingPatches document. Although, it's possible
they downloaded the tarball and built from source so they would have the
file.

Now I'm starting to dislike this whole paragraph because git isn't used
exclusively for open source software. Seems like others agree with a
little searching of gmane[1]
I think Andreas Ericsson's version with Jeff King's updates would be good.

Junio, I would say drop this patch.


[1] http://thread.gmane.org/gmane.comp.version-control.git/115299

[PATCHv2 5/8] git-format-patch.txt: general rewordings and cleanups

[Stephen Boyd]

Clarify --no-binary description using some words from the original
commit 37c22a4b (add --no-binary, 2008-05-9). Cleanup --suffix
description. Add --thread style option to synopsis and reorganize it a
bit. Clarify renaming patches example and the configuration paragraph.

Signed-off-by: Stephen Boyd <bebarino@gmail.com>
---

    Fix some issues brought up by Michael J Gruber

 Documentation/git-format-patch.txt |   38 ++++++++++++++++++------------------
 1 files changed, 19 insertions(+), 19 deletions(-)

diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt
index 4a43c64..6f1fc80 100644
--- a/Documentation/git-format-patch.txt
+++ b/Documentation/git-format-patch.txt
@@ -9,10 +9,10 @@ git-format-patch - Prepare patches for e-mail submission
 SYNOPSIS
 --------
 [verse]
-'git format-patch' [-k] [-o <dir> | --stdout] [--thread]
-		   [--attach[=<boundary>] | --inline[=<boundary>] |
-		     [--no-attach]]
-		   [-s | --signoff] [<common diff options>]
+'git format-patch' [-k] [(-o|--output-directory) <dir> | --stdout]
+		   [--thread[=<style>]]
+		   [(--attach|--inline)[=<boundary>] | --no-attach]
+		   [-s | --signoff]
 		   [-n | --numbered | -N | --no-numbered]
 		   [--start-number <n>] [--numbered-files]
 		   [--in-reply-to=Message-Id] [--suffix=.<sfx>]
@@ -20,6 +20,7 @@ SYNOPSIS
 		   [--subject-prefix=Subject-Prefix]
 		   [--cc=<email>]
 		   [--cover-letter]
+		   [<common diff options>]
 		   [ <since> | <revision range> ]
 
 DESCRIPTION
@@ -170,18 +171,17 @@ if that is not set.
 --suffix=.<sfx>::
 	Instead of using `.patch` as the suffix for generated
 	filenames, use specified suffix.  A common alternative is
-	`--suffix=.txt`.
+	`--suffix=.txt`.  Leaving this empty will remove the `.patch`
+	suffix.
 +
-Note that you would need to include the leading dot `.` if you
-want a filename like `0001-description-of-my-change.patch`, and
-the first letter does not have to be a dot.  Leaving it empty would
-not add any suffix.
+Note that the leading character does not have to be a dot; for example,
+you can use `--suffix=-patch` to get `0001-description-of-my-change-patch`.
 
 --no-binary::
-	Don't output contents of changes in binary files, just take note
-	that they differ.  Note that this disable the patch to be properly
-	applied.  By default the contents of changes in those files are
-	encoded in the patch.
+	Do not output contents of changes in binary files, instead
+	display a notice that those files changed.  Patches generated
+	using this option cannot be applied properly, but they are
+	still useful for code review.
 
 --root::
 	Treat the revision argument as a <revision range>, even if it
@@ -192,10 +192,10 @@ not add any suffix.
 
 CONFIGURATION
 -------------
-You can specify extra mail header lines to be added to each message
-in the repository configuration, new defaults for the subject prefix
-and file suffix, control attachments, and number patches when outputting
-more than one.
+You can specify extra mail header lines to be added to each message,
+defaults for the subject prefix and file suffix, number patches when
+outputting more than one patch, add "Cc:" headers, configure attachments,
+and sign off patches with configuration variables.
 
 ------------
 [format]
@@ -243,8 +243,8 @@ $ git format-patch -M -B origin
 +
 Additionally, it detects and handles renames and complete rewrites
 intelligently to produce a renaming patch.  A renaming patch reduces
-the amount of text output, and generally makes it easier to review it.
-Note that the "patch" program does not understand renaming patches, so
+the amount of text output, and generally makes it easier to review.
+Note that non-git "patch" programs won't understand renaming patches, so
 use it only when you know the recipient uses git to apply your patch.
 
 * Extract three topmost commits from the current branch and format them
-- 
1.6.2.3

Re: [PATCHv2 5/8] git-format-patch.txt: general rewordings and cleanups

[Junio C Hamano]

Thanks, both.