Re: [PATCH/RFC] Cleanup Documentation

From: Stefan Beller <sbeller@google.com>
Date: Jun 20, 2017, 17:05 UTC
Message-ID: <CAGZ79kbJB8dFUYu_70TAYbFWxLQiACEWMrE8M71GSEpnXqqzQQ@mail.gmail.com>
In-Reply-To: <CAGZ79kbJx4p2y6Vjp3dVBP2pd=MYa_j3Mxfv=zUygHY-bHj0wQ@mail.gmail.com>

On Tue, Jun 20, 2017 at 9:57 AM, Stefan Beller <sbeller@google.com> wrote:

>
> With or without this nit addressed, this patch looks good to me,
>

Well actually not quite. The subject (and commit message) is very vague, maybe:

    Documentation/git-submodule: cleanup "add" section

    The "add" section for 'git-submodule' is redundant in its description and
    the short synopsis line. Remove the redundant mentioning of the
    'repository' argument being mandatory.

    The text is hard to read because of back-references, so remove those.

    Replace the word "humanish" by "canonical" as that conveys better what
    we do to guess the path.

    While at it, quote all occurrences of '.gitmodules' as that is an important
    file in the submodule context, also link to it on its first mention.
    (This paragraph is not exactly what happens in the commit, but I wrote it
    as a way how I would write commit messages. It shows the reader how
    you addressed the given problem, with the quantifiers "all" "the
first" showing
    what you think is important, and that you deliberately omitted others)