Re: [PATCH] submodule documentation: Reorder introductory paragraphs

[Stefan Beller <sbeller@google.com>]

On Thu, May 21, 2015 at 10:24 AM, Junio C Hamano <gitster@pobox.com> wrote:
> Stefan Beller <sbeller@google.com> writes:
>
>> Reorder the paragraphs such that
>> the first short paragraph introduces the submodule concept,
>> the second paragraph highlights the usage of the submodule command,
>> the third paragraph giving background information,
>> and finally the fourth paragraph discusing alternatives such
>> as subtrees and remotes, which we don't want to be confused with.
>>
>> This ordering deepens the knowledge on submodules with each paragraph.
>> First the basic questions like "How/what" will be answered, while the
>> underlying concepts will be taught at a later time.
>
> Sounds good.
>
>> diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
>> index 2c25916..6c38c0d 100644
>> --- a/Documentation/git-submodule.txt
>> +++ b/Documentation/git-submodule.txt
>> @@ -25,35 +25,12 @@ SYNOPSIS
>>
>>  DESCRIPTION
>>  -----------
>> -Submodules allow foreign repositories to be embedded within
>> -a dedicated subdirectory of the source tree, always pointed
>> -at a particular commit.
>> +Submodules allow other repositories to be embedded within
>> +a dedicated subdirectory of the source tree pointing
>> +at a particular commit in the other repository.
>
> Not a new problem, but I can misread this as if it requires the
> top-level superproject to have one single dedicated directory D to
> house all the foreign projects under it, D/project1, D/project2, ...

I agree, maybe we should reword the paragraphs themselves as well.

    Submodules allow you to keep another Git repository in a subdirectory
    of your repository. The other repository has its own history, which does not
    interfere with the history of the current repository. This can be used to
    have external dependencies such as libraries for example.

>
>> -This command will manage the tree entries and contents of the
>> -gitmodules file for you, as well as inspect the status of your
>> -submodules and update them.
>> +This command will manage the submodules for you, as well as
>> +inspect the status of your submodules and update them.
>
> Not a new problem, but does the command really "manage them for
> you"?  I view it more like "You can use this command to manage,
> inspect and update the submodules".

I agree.