Re: [PATCH v2 1/6] doc: add new gitmergeconflicts man page

[Junio C Hamano <gitster@pobox.com>]

"Julia Evans" <julia@jvns.ca> writes:

Comments on a few more points.

>> Is it deliberate to omit 'am -3' and 'checkout -m', perhaps in order
>> to limit ourselves to most common ways to help new people by keeping
>> the description to the absolute minimum?
>
> It's deliberate, we talked about that a bit in the discussion of the v1.
> Can add a note in the commit message.

Being a part of _the_ technical manual on Git, I would like to see
us aim for completeness, and where we don't leave a note that the
description is not complete.  In this case,  between

    Merge conflicts can happen during a `git merge`, `git rebase`, `git
    cherry-pick`, `git pull`, `git am -3`, `git checkout -m`, `git
    stash pop`, or `git revert`.

that aims for completeness and

    Merge conflicts can happen during a `git merge`, `git rebase`, `git
    cherry-pick`, `git pull`, or `git revert`, and other operations.

that admits the list is not complete, I have slight preference to
the first one.

>> By the way, is it just me who finds those "Here's", "there's"
>> contractions disturbing in an official manual?  I've seen many of
>> them while reviewing this to be annoyed enough and had to blurt it
>> out X-<.
>
> I find "here is" and "there is" to be distracting and overly formal,
> different people are different I guess :)

But I wouldn't want you to be "different" here.  This is not your
diary or personal note.  This being a part of the technical manual,
I would prefer to see the same formalness applied everywhere.