Re: [PATCH] submodule documentation: Reorder introductory paragraphs

> It's better to start the man page with a description of what 
> submodules
> actually are instead of saying what they are not.
>
> 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.
>
> Making sure it is not confused with subtrees and remotes is not really
> enhancing knowledge of submodules itself, but rather painting the big
> picture of git concepts, so you could also argue to have it as the 
> second
> paragraph. Personally I think this may confuse readers, specially 
> newcomers
> though.
>
> Signed-off-by: Stefan Beller <sbeller@google.com>
> ---
> Documentation/git-submodule.txt | 54 
> ++++++++++++++++++++---------------------
> 1 file changed, 26 insertions(+), 28 deletions(-)
>
> 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.
>
> -They are not to be confused with remotes, which are meant mainly
> -for branches of the same project; submodules are meant for
> -different projects you would like to make part of your source tree,
> -while the history of the two projects still stays completely
> -independent and you cannot modify the contents of the submodule
> -from within the main project.
> -If you want to merge the project histories and want to treat the
> -aggregated whole as a single project from then on, you may want to
> -add a remote for the other project and use the 'subtree' merge 
> strategy,
> -instead of treating the other project as a submodule. Directories
> -that come from both projects can be cloned and checked out as a whole
> -if you choose to go that route.
> -
> -Submodules are composed from a so-called `gitlink` tree entry
> -in the main repository that refers to a particular commit object
> -within the inner repository that is completely separate.
> -A record in the `.gitmodules` (see linkgit:gitmodules[5]) file at the
> -root of the source tree assigns a logical name to the submodule and
> -describes the default URL the submodule shall be cloned from.
> -The logical name can be used for overriding this URL within your
> -local repository configuration (see 'submodule init').
> -
> -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.
> When adding a new submodule to the tree, the 'add' subcommand
> is to be used.  However, when pulling a tree containing submodules,
> these will not be checked out by default;
> @@ -64,6 +41,27 @@ using the 'status' subcommand and get a detailed 
> overview of the
> difference between the index and checkouts using the 'summary'
> subcommand.
>
> +Submodules are composed from a so-called `gitlink` tree entry
> +in the main repository that refers to a particular commit object
> +within the inner repository that is completely separate.
> +A record in the `.gitmodules` (see linkgit:gitmodules[5]) file at the
> +root of the source tree assigns a logical name to the submodule and
> +describes the default URL the submodule shall be cloned from.
> +The logical name can be used for overriding this URL within your
> +local repository configuration (see 'submodule init').
> +
> +Submodules are not to be confused with remotes, which are meant
> +mainly for branches of the same project;

>  submodules are meant for
> +different projects you would like to make part of your source tree,
> +while the history of the two projects still stays completely
> +independent and you cannot modify the contents of the submodule
> +from within the main project.
> +If you want to merge the project histories and want to treat the
> +aggregated whole as a single project from then on, you may want to
> +add a remote for the other project and use the 'subtree' merge 
> strategy,
> +instead of treating the other project as a submodule. Directories
> +that come from both projects can be cloned and checked out as a whole
> +if you choose to go that route.
>