[PATCH] Documentation: git-format-patch.txt rewordings and cleanups

[PATCH] Documentation: git-format-patch.txt 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 and
--thread descriptions. Add --thread style option to synopsis. Clarify
renaming patches example.

Signed-off-by: Stephen Boyd <bebarino@gmail.com>
---
Is the synopsis getting too heavy? Maybe it should be changed to:

    git format-patch [<options>] [<common diff options>] [<revision range>]

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

diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt
index c2eb5fa..f31098b 100644
--- a/Documentation/git-format-patch.txt
+++ b/Documentation/git-format-patch.txt
@@ -9,9 +9,9 @@ git-format-patch - Prepare patches for e-mail submission
 SYNOPSIS
 --------
 [verse]
-'git format-patch' [-k] [-o <dir> | --stdout] [--thread]
+'git format-patch' [-k] [-o <dir> | --stdout] [--thread[=<style>]]
 		   [--attach[=<boundary>] | --inline[=<boundary>] |
-		     [--no-attach]]
+		    --no-attach]
 		   [-s | --signoff] [<common diff options>]
 		   [-n | --numbered | -N | --no-numbered]
 		   [--start-number <n>] [--numbered-files]
@@ -132,9 +132,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.
@@ -169,24 +169,24 @@ 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 first letter is not required to be a dot, you will need to
+include the leading dot `.` if you want a filename like
+`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.
 
 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 attachements, and number patches when outputting
+in the repository configuration, defaults for the subject prefix
+and file suffix, configure attachments, and number patches when outputting
 more than one.
 
 ------------
@@ -234,8 +234,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

Re: [PATCH] Documentation: git-format-patch.txt rewordings and cleanups

[J. Bruce Fields]

On Mon, Mar 23, 2009 at 03:21:23AM -0700, Stephen Boyd wrote:
> Clarify --no-binary description using some words from the original
> commit 37c22a4b (add --no-binary, 2008-05-9). Cleanup --suffix and
> --thread descriptions. Add --thread style option to synopsis. Clarify
> renaming patches example.
> 
> Signed-off-by: Stephen Boyd <bebarino@gmail.com>
> ---
> Is the synopsis getting too heavy? Maybe it should be changed to:
> 
>     git format-patch [<options>] [<common diff options>] [<revision range>]
> 
>  Documentation/git-format-patch.txt |   34 +++++++++++++++++-----------------
>  1 files changed, 17 insertions(+), 17 deletions(-)
> 
> diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt
> index c2eb5fa..f31098b 100644
> --- a/Documentation/git-format-patch.txt
> +++ b/Documentation/git-format-patch.txt
> @@ -9,9 +9,9 @@ git-format-patch - Prepare patches for e-mail submission
>  SYNOPSIS
>  --------
>  [verse]
> -'git format-patch' [-k] [-o <dir> | --stdout] [--thread]
> +'git format-patch' [-k] [-o <dir> | --stdout] [--thread[=<style>]]
>  		   [--attach[=<boundary>] | --inline[=<boundary>] |
> -		     [--no-attach]]
> +		    --no-attach]
>  		   [-s | --signoff] [<common diff options>]
>  		   [-n | --numbered | -N | --no-numbered]
>  		   [--start-number <n>] [--numbered-files]
> @@ -132,9 +132,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.
> @@ -169,24 +169,24 @@ 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 first letter is not required to be a dot, you will need to
> +include the leading dot `.` if you want a filename like
> +`0001-description-of-my-change.patch`.

That's a comma-splice, trivially fixed by changing "dot, you" to "dot;
you".

Better?: "Note that the leading dot isn't actually required if you don't
want a dot between the patch name and the suffix."

(Though personally I'd strike the whole sentence, since a) probably
nobody cares, and b) the 1 in a million person that does actually want
to do this can figure it out easily enough on their own with a quick
test.)

--b.

>  
>  --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.
>  
>  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 attachements, and number patches when outputting
> +in the repository configuration, defaults for the subject prefix
> +and file suffix, configure attachments, and number patches when outputting
>  more than one.
>  
>  ------------
> @@ -234,8 +234,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
> 
> --
> To unsubscribe from this list: send the line "unsubscribe git" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] Documentation: git-format-patch.txt rewordings and cleanups

[Stephen Boyd]

On Tue, Mar 24, 2009 at 3:09 PM, J. Bruce Fields <bfields@fieldses.org> wrote:
> On Mon, Mar 23, 2009 at 03:21:23AM -0700, Stephen Boyd wrote:
>>  +
>> -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 first letter is not required to be a dot, you will need to
>> +include the leading dot `.` if you want a filename like
>> +`0001-description-of-my-change.patch`.
>
> That's a comma-splice, trivially fixed by changing "dot, you" to "dot;
> you".
>
> Better?: "Note that the leading dot isn't actually required if you don't
> want a dot between the patch name and the suffix."
>
> (Though personally I'd strike the whole sentence, since a) probably
> nobody cares, and b) the 1 in a million person that does actually want
> to do this can figure it out easily enough on their own with a quick
> test.)
>
> --b.
>

I don't think documentation is meant to point the user to trial and
error. Even if the error is fairly harmless. Although you could be
right that nobody cares.

How about a sentence with no negation?

"Note that the leading dot is required if you want a dot between the
patch name and the suffix."

Re: [PATCH] Documentation: git-format-patch.txt rewordings and cleanups

[J. Bruce Fields]

On Tue, Mar 24, 2009 at 04:36:15PM -0700, Stephen Boyd wrote:
> On Tue, Mar 24, 2009 at 3:09 PM, J. Bruce Fields <bfields@fieldses.org> wrote:
> > On Mon, Mar 23, 2009 at 03:21:23AM -0700, Stephen Boyd wrote:
> >>  +
> >> -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 first letter is not required to be a dot, you will need to
> >> +include the leading dot `.` if you want a filename like
> >> +`0001-description-of-my-change.patch`.
> >
> > That's a comma-splice, trivially fixed by changing "dot, you" to "dot;
> > you".
> >
> > Better?: "Note that the leading dot isn't actually required if you don't
> > want a dot between the patch name and the suffix."
> >
> > (Though personally I'd strike the whole sentence, since a) probably
> > nobody cares, and b) the 1 in a million person that does actually want
> > to do this can figure it out easily enough on their own with a quick
> > test.)
> >
> > --b.
> >
> 
> I don't think documentation is meant to point the user to trial and
> error. Even if the error is fairly harmless. Although you could be
> right that nobody cares.
> 
> How about a sentence with no negation?
> 
> "Note that the leading dot is required if you want a dot between the
> patch name and the suffix."

Sure!

--b.

Re: [PATCH] Documentation: git-format-patch.txt rewordings and cleanups

[Junio C Hamano]

Stephen Boyd <bebarino@gmail.com> writes:

> How about a sentence with no negation?
>
> "Note that the leading dot is required if you want a dot between the
> patch name and the suffix."

How about a sentence that does not sound requirement but freedom?

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

Re: [PATCH] Documentation: git-format-patch.txt rewordings and cleanups

[Stephen Boyd]

On Tue, Mar 24, 2009 at 4:55 PM, Junio C Hamano <gitster@pobox.com> wrote:
> Stephen Boyd <bebarino@gmail.com> writes:
>
>> How about a sentence with no negation?
>>
>> "Note that the leading dot is required if you want a dot between the
>> patch name and the suffix."
>
> How about a sentence that does not sound requirement but freedom?
>
> "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".

Looks even better. Do we still want to start off by saying "Note that the..." ?

Re: [PATCH] Documentation: git-format-patch.txt rewordings and cleanups

[Junio C Hamano]

Stephen Boyd <bebarino@gmail.com> writes:

> On Tue, Mar 24, 2009 at 4:55 PM, Junio C Hamano <gitster@pobox.com> wrote:
>> Stephen Boyd <bebarino@gmail.com> writes:
>>
>>> How about a sentence with no negation?
>>>
>>> "Note that the leading dot is required if you want a dot between the
>>> patch name and the suffix."
>>
>> How about a sentence that does not sound requirement but freedom?
>>
>> "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".
>
> Looks even better. Do we still want to start off by saying "Note that the..." ?

Perhaps; I wasn't paying much attention to the whole sentence, but was
primarily interested about giving the description less negative
connotation.