[PATCH] Documentation/git-add.txt: Explain --patch option in layman terms

[PATCH] Documentation/git-add.txt: Explain --patch option in layman terms

[Jari Aalto]

Signed-off-by: Jari Aalto <jari.aalto@cante.net>
---
 Documentation/git-add.txt |   10 +++++-----
 1 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt
index e67b7e8..71990c2 100644
--- a/Documentation/git-add.txt
+++ b/Documentation/git-add.txt
@@ -67,14 +67,14 @@ OPTIONS
 --interactive::
 	Add modified contents in the working tree interactively to
 	the index. Optional path arguments may be supplied to limit
-	operation to a subset of the working tree. See ``Interactive
-	mode'' for details.
+	operation to a subset of the working tree. See section
+	``INTERACTIVE MODE'' for details.
 
 -p::
 --patch::
-	Similar to Interactive mode but the initial command loop is
-	bypassed and the 'patch' subcommand is invoked using each of
-	the specified filepatterns before exiting.
+	Run interactive patch command for each file on command line.
+	See section INTERACTIVE MODE and patch subcommand for more
+	information.
 
 -e, \--edit::
 	Open the diff vs. the index in an editor and let the user
-- 
1.6.3.3

Re: [PATCH] Documentation/git-add.txt: Explain --patch option in layman terms

[Junio C Hamano]

Jari Aalto <jari.aalto@cante.net> writes:

> Signed-off-by: Jari Aalto <jari.aalto@cante.net>
> ---
>  Documentation/git-add.txt |   10 +++++-----
>  1 files changed, 5 insertions(+), 5 deletions(-)
>
> diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt
> index e67b7e8..71990c2 100644
> --- a/Documentation/git-add.txt
> +++ b/Documentation/git-add.txt
> @@ -67,14 +67,14 @@ OPTIONS
>  --interactive::
>  	Add modified contents in the working tree interactively to
>  	the index. Optional path arguments may be supplied to limit
> -	operation to a subset of the working tree. See ``Interactive
> -	mode'' for details.
> +	operation to a subset of the working tree. See section
> +	``INTERACTIVE MODE'' for details.

Sorry, the change in this hunk does not make *any* sense to me.

It is not justified with your commit log message, I do not see why you
have to shout in all CAPS, and there is no such section in the
documentation.  But the "Interactive mode" section exists and is referred
to by the original.

>  -p::
>  --patch::
> -	Similar to Interactive mode but the initial command loop is
> -	bypassed and the 'patch' subcommand is invoked using each of
> -	the specified filepatterns before exiting.
> +	Run interactive patch command for each file on command line.
> +	See section INTERACTIVE MODE and patch subcommand for more
> +	information.

I personally think fixing misworded phrase "initial command loop" would be
sufficient.  It should read "initial command menu".  Perhaps like this.

	Run ``add --interactive``, but bypass the initial command menu and
	directly jump to `patch` subcommand.  See ``Interactive mode'' for
	details.

If you assume that the reader is not familiar with "add -i", then the
above is not descriptive enough, but "Run interactive patch command" is
not an improvement either.  We would need a description of "what it is
used for" before "how it would look to you" (i.e.. my rewrite shown
above).

"What it is used for" would perhaps read like this.

	Review the difference between the index and the work tree, and add
	modified contents to the index interactively by choosing which
	patch hunks to use.

Re: [PATCH] Documentation/git-add.txt: Explain --patch option in layman terms

[Jeff King]

On Sun, Aug 30, 2009 at 01:14:24PM -0700, Junio C Hamano wrote:

> > -	operation to a subset of the working tree. See ``Interactive
> > -	mode'' for details.
> > +	operation to a subset of the working tree. See section
> > +	``INTERACTIVE MODE'' for details.
> 
> Sorry, the change in this hunk does not make *any* sense to me.
> 
> It is not justified with your commit log message, I do not see why you
> have to shout in all CAPS, and there is no such section in the
> documentation.  But the "Interactive mode" section exists and is referred
> to by the original.

I think it is an attempt to match the way docbook renders manpage
headings; it converts headings to all-caps. And there is some precedent;
try grepping for ".EXAMPLES" in Documentation/*.txt.

That being said, the straight asciidoc->html version leaves the
capitalization untouched. However, that actually makes the html version
look quite awkward. Some of the headings are in all-caps and some are
not. So I wonder if we should make them typographically consistent.

(And yes, I totally agree that this hunk was a surprise after reading
the commit message and if anything is done, it should be in a separate
patch).

-Peff

Re: [PATCH] Documentation/git-add.txt: Explain --patch option in layman terms

[Jari Aalto]

Junio C Hamano <gitster@pobox.com> writes:

> Jari Aalto <jari.aalto@cante.net> writes:
>
>> Signed-off-by: Jari Aalto <jari.aalto@cante.net>
>> ---
>>  Documentation/git-add.txt |   10 +++++-----
>>  1 files changed, 5 insertions(+), 5 deletions(-)
>>
>> diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt
>> index e67b7e8..71990c2 100644
>> --- a/Documentation/git-add.txt
>> +++ b/Documentation/git-add.txt
>> @@ -67,14 +67,14 @@ OPTIONS
>>  --interactive::
>>  	Add modified contents in the working tree interactively to
>>  	the index. Optional path arguments may be supplied to limit
>> -	operation to a subset of the working tree. See ``Interactive
>> -	mode'' for details.
>> +	operation to a subset of the working tree. See section
>> +	``INTERACTIVE MODE'' for details.
>
> It is not justified with your commit log message, I do not see why you
> have to shout in all CAPS, and there is no such section in the
> documentation.  But the "Interactive mode" section exists and is referred
> to by the original.

It is not shouting, but standard practise to refer to manual page
section in ALL CAPS, when they are top level headings, like in this
case.

>>  -p::
>>  --patch::
>> -	Similar to Interactive mode but the initial command loop is
>> -	bypassed and the 'patch' subcommand is invoked using each of
>> -	the specified filepatterns before exiting.
>> +	Run interactive patch command for each file on command line.
>> +	See section INTERACTIVE MODE and patch subcommand for more
>> +	information.
>
> I personally think fixing misworded phrase "initial command loop" would be
> sufficient.  It should read "initial command menu".  Perhaps like this.
>
> 	Run ``add --interactive``, but bypass the initial command menu and
> 	directly jump to `patch` subcommand.  See ``Interactive mode'' for
> 	details.

It's still too technical. The 1st line should go right into business:

 	Patch each file on command line interactively. This is this is
 	the same as ``add --interactive``, but bypass the initial
 	command menu and directly jump to `patch` subcommand. See
 	``Interactive mode'' for details.

Jari

Re: [PATCH] Documentation/git-add.txt: Explain --patch option in layman terms

[Junio C Hamano]

Jari Aalto <jari.aalto@cante.net> writes:

> It is not shouting, but standard practise to refer to manual page
> section in ALL CAPS, when they are top level headings, like in this
> case.

Why are you making excuses, ignoring the fact that you didn't have a
matching update to make the section also in caps in the patch?

Sections that are common in all manual pages (e.g. NAME, SYNOPSIS,
DESCRIPTION, EXAMPLES, SEE ALSO) are often spelled in and referred to in
caps.  You do not have to explain that to me ;-)

If you wanted to add "Interactive mode" to that set of "common sections"
and spell it in caps, do so consistently.

See http://www.kernel.org/pub/software/scm/git/docs/git-add.html#_interactive_mode
for what I mean.

>> I personally think fixing misworded phrase "initial command loop" would be
>> sufficient.  It should read "initial command menu".  Perhaps like this.
>>
>> 	Run ``add --interactive``, but bypass the initial command menu and
>> 	directly jump to `patch` subcommand.  See ``Interactive mode'' for
>> 	details.
>
> It's still too technical. The 1st line should go right into business:
>
>  	Patch each file on command line interactively. This is this is
>  	the same as ``add --interactive``, but bypass the initial
>  	command menu and directly jump to `patch` subcommand. See
>  	``Interactive mode'' for details.

Even if we ignore the double "this is this is", I do not think it is
better than the original.

What does "Patch each file" mean?  When read naively (and that is the
whole point of your "too technical" comment), a reader would expect there
will be changes made _to_ the work tree files.

If you want to start the description with "What it does/what it is used
for", I think it is a good idea.  I already made a suggestion for such an
improvement in my message you are responding to.

If you want to make a counterproposal, at least please do that with a
counter-proposal that is better.

Re: [PATCH] Documentation/git-add.txt: Explain --patch option in layman terms

[Jari Aalto]

Junio C Hamano <gitster@pobox.com> writes:

> Sections that are common in all manual pages (e.g. NAME, SYNOPSIS,
> DESCRIPTION, EXAMPLES, SEE ALSO) are often spelled in and referred to in
> caps. 

Not just common ones. All sections that are top level heading are best
spelled out consistently. Examples can be found from the URL to
POSIX/Susv in my other post.

[I'll get back to the CAPS patch in anaother post if we can sort this out]

> See http://www.kernel.org/pub/software/scm/git/docs/git-add.html#_interactive_mode
> for what I mean.

I think the convention used in git's manual pages deviate from the
standard practise. We could make the git manual pages into line of:

- write all the first level headings in all caps: "HEADING LIKE THIS"
- write second level heading: start Upper-lower: "Heading like this"

Cf. rsync(1), ssh(1) etc. many pages prior git's existense.

>>> I personally think fixing misworded phrase "initial command loop" would be
>>> sufficient.  It should read "initial command menu".  Perhaps like this.
>>>
>>> 	Run ``add --interactive``, but bypass the initial command menu and
>>> 	directly jump to `patch` subcommand.  See ``Interactive mode'' for
>>> 	details.
>>
>> It's still too technical. The 1st line should go right into business:
>>
>>  	Patch each file on command line interactively. This is this is
>>  	the same as ``add --interactive``, but bypass the initial
>>  	command menu and directly jump to `patch` subcommand. See
>>  	``Interactive mode'' for details.
>
> I do not think it is better than the original.

Your proposal that starts:

    ...but bypass the initial command menu

Mine:

    Patch each file on command line interactively

The first line should somehow strike immediately what the command does.
I would like to see a suggestion that has 'patch(ing)' somewhere at the
very first row. I hope we can find compromise.

Jari

Re: [PATCH] Documentation/git-add.txt: Explain --patch option in layman terms

[Junio C Hamano]

Jari Aalto <jari.aalto@cante.net> writes:

> Your proposal that starts:
>
>     ...but bypass the initial command menu

No, it doesn't..

Go re-read the message you are responding to, paying extra attention to
the parts you snipped from your quote, which was the important part you
should have read before you responded.

    If you want to start the description with "What it does/what it is used
    for", I think it is a good idea.  I already made a suggestion for such an
    improvement in my message you are responding to.

Now, what was that suggestion?

It is in the message your first response was a follow-up to.  Again you
didn't quote the relevant part in that response, and perhaps that was
because you did not even read it before responding.

    If you assume that the reader is not familiar with "add -i", then the
    above is not descriptive enough, but "Run interactive patch command" is
    not an improvement either.  We would need a description of "what it is
    used for" before "how it would look to you" (i.e.. my rewrite shown
    above).

    "What it is used for" would perhaps read like this.

            Review the difference between the index and the work tree, and add
            modified contents to the index interactively by choosing which
            patch hunks to use.

This time I re-quoted things for you because your responses obviously were
written without reading or understanding them, but please be careful not
to make me do this.  I do not have infinite time.

Re: [PATCH] Documentation/git-add.txt: Explain --patch option in layman terms

[Jari Aalto]

Junio C Hamano <gitster@pobox.com> writes:

I apologize if you though I did not read. I did, but I the separate
paragraph order did not meet here as you might have intended.

To recap, your suggestion, if read correct:

    --patch:
    -p::
        Review the difference between the index and the work tree, and add
        modified contents to the index interactively by choosing which
        patch hunks to use.

        Run ``add --interactive``, but bypass the initial command menu and
        directly jump to `patch` subcommand.  See ``Interactive mode'' for
        details.

For more direct first line, howabout:

    --patch:
    -p::
        In a modified work tree, choose interactively which patch hunks to
        add. This gives a change to review the difference between the
        index and the work before adding modified contents to the index.

        This effectively runs ``add --interactive``, but bypass the
        initial command menu and directly jump to `patch` subcommand.
        See ``Interactive mode'' for details.

Jari

Re: [PATCH] Documentation/git-add.txt: Explain --patch option in layman terms

[Junio C Hamano]

Jari Aalto <jari.aalto@cante.net> writes:

>     --patch:
>     -p::
>         In a modified work tree, choose interactively which patch hunks to
>         add. This gives a change to review the difference between the
>         index and the work before adding modified contents to the index.

Sounds sensible.  You may want to be even more direct and succinct, e.g.

    Interactively choose hunks of patch between the index and the work
    tree and add them to the index.

[PATCH] Improve --patch option documentation in git-add

[Jari Aalto]

Junio C Hamano <gitster@pobox.com> writes:

> Jari Aalto <jari.aalto@cante.net> writes:
>
>>     --patch:
>>     -p::
>>         In a modified work tree, choose interactively which patch hunks to
>>         add. This gives a change to review the difference between the
>>         index and the work before adding modified contents to the index.
>
> Sounds sensible.  You may want to be even more direct and succinct, e.g.
>
>     Interactively choose hunks of patch between the index and the work
>     tree and add them to the index.

Thanks, see below,
Jari

>From 63aa94e7782d6340ead0446ea80ed6223d7ac5c1 Mon Sep 17 00:00:00 2001
From: Jari Aalto <jari.aalto@cante.net>
Date: Sun, 13 Sep 2009 09:43:10 +0300
Subject: [PATCH] Improve --patch option documentation in git-add

Signed-off-by: Jari Aalto <jari.aalto@cante.net>
---
 Documentation/git-add.txt |   11 ++++++++---
 1 files changed, 8 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt
index e67b7e8..b94fbec 100644
--- a/Documentation/git-add.txt
+++ b/Documentation/git-add.txt
@@ -72,9 +72,14 @@ OPTIONS
 
 -p::
 --patch::
-	Similar to Interactive mode but the initial command loop is
-	bypassed and the 'patch' subcommand is invoked using each of
-	the specified filepatterns before exiting.
+	Interactively choose hunks of patch between the index and the
+	work tree and add them to the index. This gives a change to
+	review the difference before adding modified contents to the
+	index.
+
+	This effectively runs ``add --interactive``, but bypass the
+	initial command menu and directly jump to `patch` subcommand.
+	See ``Interactive mode'' for details.
 
 -e, \--edit::
 	Open the diff vs. the index in an editor and let the user
-- 
1.6.3.3

Re: [PATCH] Improve --patch option documentation in git-add

[Mikael Magnusson]

2009/9/13 Jari Aalto <jari.aalto@cante.net>:
> Junio C Hamano <gitster@pobox.com> writes:
>
>> Jari Aalto <jari.aalto@cante.net> writes:
>>
>>>     --patch:
>>>     -p::
>>>         In a modified work tree, choose interactively which patch hunks to
>>>         add. This gives a change to review the difference between the
>>>         index and the work before adding modified contents to the index.
>>
>> Sounds sensible.  You may want to be even more direct and succinct, e.g.
>>
>>     Interactively choose hunks of patch between the index and the work
>>     tree and add them to the index.
>
> Thanks, see below,
> Jari
>
> From 63aa94e7782d6340ead0446ea80ed6223d7ac5c1 Mon Sep 17 00:00:00 2001
> From: Jari Aalto <jari.aalto@cante.net>
> Date: Sun, 13 Sep 2009 09:43:10 +0300
> Subject: [PATCH] Improve --patch option documentation in git-add
>
> Signed-off-by: Jari Aalto <jari.aalto@cante.net>
> ---
>  Documentation/git-add.txt |   11 ++++++++---
>  1 files changed, 8 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt
> index e67b7e8..b94fbec 100644
> --- a/Documentation/git-add.txt
> +++ b/Documentation/git-add.txt
> @@ -72,9 +72,14 @@ OPTIONS
>
>  -p::
>  --patch::
> -       Similar to Interactive mode but the initial command loop is
> -       bypassed and the 'patch' subcommand is invoked using each of
> -       the specified filepatterns before exiting.
> +       Interactively choose hunks of patch between the index and the
diff probably makes more sense than patch here

> +       work tree and add them to the index. This gives a change to
a chance

> +       review the difference before adding modified contents to the
differences? Not sure which I prefer on this one.

> +       index.
> +
> +       This effectively runs ``add --interactive``, but bypass the
bypasses

> +       initial command menu and directly jump to `patch` subcommand.
jumps

> +       See ``Interactive mode'' for details.
>
>  -e, \--edit::
>        Open the diff vs. the index in an editor and let the user
> --
> 1.6.3.3

-- 
Mikael Magnusson

Re: [PATCH] Improve --patch option documentation in git-add

[Jari Aalto]

[-- Attachment #1: Type: text/plain, Size: 593 bytes --]

Mikael Magnusson <mikachu@gmail.com> writes:
>> +       Interactively choose hunks of patch between the index and the
> diff probably makes more sense than patch here
>
>> +       work tree and add them to the index. This gives a change to
> a chance
>
>> +       review the difference before adding modified contents to the
> differences? Not sure which I prefer on this one.
>
>> +       index.
>> +
>> +       This effectively runs ``add --interactive``, but bypass the
> bypasses
>
>> +       initial command menu and directly jump to `patch` subcommand.
> jumps

An update. Thanks,
Jari


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Improve-patch-option-documentation-in-git-add.patch --]
[-- Type: text/x-diff, Size: 1200 bytes --]

>From beca0d3dcd668e1b578588378149320cd3aed9d9 Mon Sep 17 00:00:00 2001
From: Jari Aalto <jari.aalto@cante.net>
Date: Sun, 13 Sep 2009 17:08:51 +0300
Subject: [PATCH] Improve --patch option documentation in git-add

Signed-off-by: Jari Aalto <jari.aalto@cante.net>
---
 Documentation/git-add.txt |   11 ++++++++---
 1 files changed, 8 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt
index e67b7e8..0b2a2a6 100644
--- a/Documentation/git-add.txt
+++ b/Documentation/git-add.txt
@@ -72,9 +72,14 @@ OPTIONS
 
 -p::
 --patch::
-	Similar to Interactive mode but the initial command loop is
-	bypassed and the 'patch' subcommand is invoked using each of
-	the specified filepatterns before exiting.
+	Interactively choose hunks of diff between the index and the
+	work tree and add them to the index. This gives a change to
+	review the differences before adding modified contents to the
+	index.
+
+	This effectively runs ``add --interactive``, but bypass the
+	initial command menu and directly jumps to `patch` subcommand.
+	See ``Interactive mode'' for details.
 
 -e, \--edit::
 	Open the diff vs. the index in an editor and let the user
-- 
1.6.3.3

Re: [PATCH] Improve --patch option documentation in git-add

[Sean Estabrooks]

On Sun, 13 Sep 2009 17:09:11 +0300
Jari Aalto <jari.aalto@cante.net> wrote:

> An update. Thanks,
> Jari
> 
[...]
>  -p::
> --patch::
> -	Similar to Interactive mode but the initial command loop is
> -	bypassed and the 'patch' subcommand is invoked using each of
> -	the specified filepatterns before exiting.
> +	Interactively choose hunks of diff between the index and the
> +	work tree and add them to the index. This gives a change to
> +	review the differences before adding modified contents to the
> +	index.
> +
> +	This effectively runs ``add --interactive``, but bypass the
> +	initial command menu and directly jumps to `patch` subcommand.
> +	See ``Interactive mode'' for details.


Jari,

It's good that you're working to make the documentation better.  To
me though, it seems more difficult to parse this description than the
one offered by Junio in an earlier thread:

        Review the difference between the index and the work tree, and add
        modified contents to the index interactively by choosing which
        patch hunks to use. 

If you don't want to just use that description verbatim, perhaps you'd
consider something closer to yours, such as:

	Interactively review the differences between the index and the
	work tree and choose which hunks to add into the index.

	This effectively runs ``add --interactive``, but bypasses the
	initial command menu and jumps directly to the `patch` subcommand.
	See ``Interactive mode'' for details.

Cheers,
Sean

Re: [PATCH] Improve --patch option documentation in git-add (updated patch)

[Jari Aalto]

[-- Attachment #1: Type: text/plain, Size: 565 bytes --]

Sean Estabrooks <seanlkml@sympatico.ca> writes:
> ... To me though, it seems more difficult to parse this description
> than the one offered by Junio in an earlier thread ...perhaps you'd
> consider something closer to yours, such as:
>
> 	Interactively review the differences between the index and the
> 	work tree and choose which hunks to add into the index.
>
> 	This effectively runs ``add --interactive``, but bypasses the
> 	initial command menu and jumps directly to the `patch` subcommand.
> 	See ``Interactive mode'' for details.


Updated, thanks,
Jari


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Improve-patch-option-documentation-in-git-add.patch --]
[-- Type: text/x-diff, Size: 1129 bytes --]

>From be5eebc53c2e3dcf67edfb371d8aa8263e1a8d69 Mon Sep 17 00:00:00 2001
From: Jari Aalto <jari.aalto@cante.net>
Date: Tue, 15 Sep 2009 08:33:51 +0300
Subject: [PATCH] Improve --patch option documentation in git-add

Signed-off-by: Jari Aalto <jari.aalto@cante.net>
---
 Documentation/git-add.txt |    9 ++++++---
 1 files changed, 6 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt
index e67b7e8..c57895a 100644
--- a/Documentation/git-add.txt
+++ b/Documentation/git-add.txt
@@ -72,9 +72,12 @@ OPTIONS
 
 -p::
 --patch::
-	Similar to Interactive mode but the initial command loop is
-	bypassed and the 'patch' subcommand is invoked using each of
-	the specified filepatterns before exiting.
+	Interactively review the differences between the index and the
+	work tree and choose which hunks to add into the index.
+
+	This effectively runs ``add --interactive``, but bypasses the
+	initial command menu and jumps directly to the `patch` subcommand.
+	See ``Interactive mode'' for details.
 
 -e, \--edit::
 	Open the diff vs. the index in an editor and let the user
-- 
1.6.3.3

Re: [PATCH] Improve --patch option documentation in git-add (updated patch)

[Nanako Shiraishi]

Quoting Jari Aalto <jari.aalto@cante.net>

> Sean Estabrooks <seanlkml@sympatico.ca> writes:
>> ... To me though, it seems more difficult to parse this description
>> than the one offered by Junio in an earlier thread ...perhaps you'd
>> consider something closer to yours, such as:
>>
>> 	Interactively review the differences between the index and the
>> 	work tree and choose which hunks to add into the index.
>>
>> 	This effectively runs ``add --interactive``, but bypasses the
>> 	initial command menu and jumps directly to the `patch` subcommand.
>> 	See ``Interactive mode'' for details.
>
>
> Updated, thanks,
> Jari
>
>
> From be5eebc53c2e3dcf67edfb371d8aa8263e1a8d69 Mon Sep 17 00:00:00 2001
> From: Jari Aalto <jari.aalto@cante.net>
> Date: Tue, 15 Sep 2009 08:33:51 +0300
> Subject: [PATCH] Improve --patch option documentation in git-add
>
> Signed-off-by: Jari Aalto <jari.aalto@cante.net>
> ---
>  Documentation/git-add.txt |    9 ++++++---
>  1 files changed, 6 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt
> index e67b7e8..c57895a 100644
> --- a/Documentation/git-add.txt
> +++ b/Documentation/git-add.txt
> @@ -72,9 +72,12 @@ OPTIONS
>  
>  -p::
>  --patch::
> -	Similar to Interactive mode but the initial command loop is
> -	bypassed and the 'patch' subcommand is invoked using each of
> -	the specified filepatterns before exiting.
> +	Interactively review the differences between the index and the
> +	work tree and choose which hunks to add into the index.
> +
> +	This effectively runs ``add --interactive``, but bypasses the
> +	initial command menu and jumps directly to the `patch` subcommand.
> +	See ``Interactive mode'' for details.
>  
>  -e, \--edit::
>  	Open the diff vs. the index in an editor and let the user

Sorry, but this patch doesn't seem to apply anywhere. Have you fetched recently?

-- 
Nanako Shiraishi
http://ivory.ap.teacup.com/nanako3/

Re: [PATCH] Improve --patch option documentation in git-add (updated patch)

[Jari Aalto]

Nanako Shiraishi <nanako3@lavabit.com> writes:

> Sorry, but this patch doesn't seem to apply anywhere. Have you fetched recently?

Junio merged the patch at 5f2b1e6

Jari

Re: [PATCH] Improve --patch option documentation in git-add (updated patch)

[Nanako Shiraishi]

Quoting Jari Aalto <jari.aalto@cante.net>

> Nanako Shiraishi <nanako3@lavabit.com> writes:
>
>> Sorry, but this patch doesn't seem to apply anywhere. Have you fetched recently?
>
> Junio merged the patch at 5f2b1e6

Oh, I see.

If so, could you rebase and resend?

It would also be nicer if you followed Documentation/SubmittingPatches when composing your message, writing any additional comments after the three dashes line.

Thank you.

-- 
Nanako Shiraishi
http://ivory.ap.teacup.com/nanako3/

Re: [PATCH] Documentation/git-add.txt: Explain --patch option in layman terms

[Junio C Hamano]

Jari Aalto <jari.aalto@cante.net> writes:

> I think the convention used in git's manual pages deviate from the
> standard practise. We could make the git manual pages into line of:
>
> - write all the first level headings in all caps: "HEADING LIKE THIS"
> - write second level heading: start Upper-lower: "Heading like this"
>
> Cf. rsync(1), ssh(1) etc. many pages prior git's existense.

Having seen that nothing happened after a separate thread that was also on
the documentation consistency:

    http://thread.gmane.org/gmane.comp.version-control.git/72163/focus=72213

I am having a hard time to decide how seriously I should take the above
comment from you.

Are you volunteering to coordinate such a change (in other words, you do
not necessarily have to do _all_ the work yourself, alone), or is it just
an idle speculation?

Re: [PATCH] Documentation/git-add.txt: Explain --patch option in layman terms

[Jari Aalto]

Junio C Hamano <gitster@pobox.com> writes:

> Jari Aalto <jari.aalto@cante.net> writes:
>
>> I think the convention used in git's manual pages deviate from the
>> standard practise. We could make the git manual pages into line of:
>>
>> - write all the first level headings in all caps: "HEADING LIKE THIS"
>> - write second level heading: start Upper-lower: "Heading like this"
>>
>> Cf. rsync(1), ssh(1) etc. many pages prior git's existense.
>

[URL: That's a separate issue. The resolution hung in the air how to
proceed]

Please be patient. I understand that you have lot work. I do care,
therefore I take the time to suggest some chnages.

> Are you volunteering to coordinate such a change (in other words, you do
> not necessarily have to do _all_ the work yourself, alone)

We need resolution first. What would you think about that change?

I could offer patches, but not in any time frame to do it in one-swoop
do-it-all patch. To distribute time and effort to do so, it would be
sensible to handle one manual at a time. The whole work would eventually
get done.

There could be section in TODO.

    RFH - Request for help: Manual page adjustments

    - If you have some spare time, the following manual pages adjustment
      is needed for all git manuals ....

Or 2-weekly RFH post could announce the need. That would be one way to
coordinate participants.

Jari

Re: [PATCH] Documentation/git-add.txt: Explain --patch option in layman terms

[Junio C Hamano]

Jari Aalto <jari.aalto@cante.net> writes:

> I could offer patches, but not in any time frame to do it in one-swoop
> do-it-all patch. To distribute time and effort to do so, it would be
> sensible to handle one manual at a time. The whole work would eventually
> get done.

Yeah, that's the spirit, and that is why I said you do not necessarily
have to do all the work yourself.  It would be expected of that volunteer
to keep an eye on patches other helpful folks may send to cover the issue,
vet them to make sure they do not introduce silly typos, AsciiDoc
breakages, and needless conflicts.

As to guidelines, I think your "spell all top-level headlines in caps" is
a reasonable one, as "man" backend for AsciiDoc does that anyway.

For the ancient "Synopsis" issue, SD5-XCU-ERN-97 would be a reasonable
guideline to follow (http://www.opengroup.org/austin/docs/austin_325.txt).

> There could be section in TODO.
>
>     RFH - Request for help: Manual page adjustments
>
>     - If you have some spare time, the following manual pages adjustment
>       is needed for all git manuals ....
>
> Or 2-weekly RFH post could announce the need. That would be one way to
> coordinate participants.

I would leave such a procedural issue to the volunteer who heads the
effort to decide.  If you are asking me to decide, then you are not
volunteering yourself, but you are volunteering _me_ for the job ;-).

Thanks.

Re: [PATCH] Documentation/git-add.txt: Explain --patch option in layman terms

[Jari Aalto]

Junio C Hamano <gitster@pobox.com> writes:

>> +	operation to a subset of the working tree. See section
>> +	``INTERACTIVE MODE'' for details.
>
> It is not justified with your commit log message, I do not see why you
> have to shout in all CAPS, 

There are plenty of examples, that it's standard practise to refer top
level headings, in all caps, from:

    POSIX/SusV guides for manual pages: "1.11 Utility Description Defaults"
    http://www.opengroup.org/onlinepubs/009695399/utilities/xcu_chap01.html#tag_01_11

Jari