patchDocumentation/git-add.txt: Explain --patch option in layman terms

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

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

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

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

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

Junio C Hamano <gitster@pobox.com> 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.

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

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

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.

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.

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

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]

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.

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

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

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.

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

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

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.

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

Thanks, see below, Jari

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(-)

2009/9/13 Jari Aalto <jari.aalto@cante.net>:

diff probably makes more sense than patch here

a chance

differences? Not sure which I prefer on this one.

bypasses

jumps

Mikael Magnusson <mikachu@gmail.com> writes:

An update. Thanks, Jari

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(-)

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

[...]

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

Sean Estabrooks <seanlkml@sympatico.ca> writes:

Updated, thanks, Jari

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(-)

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

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

Nanako Shiraishi <nanako3@lavabit.com> writes:

Junio merged the patch at 5f2b1e6

Jari

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

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.

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

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?

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

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

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

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

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

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.

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

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