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.
>
> Additionally to reordering the paragraphs, they have been slightly
> reworded.
>
> Signed-off-by: Stefan Beller <sbeller@google.com>
> ---
>
> For now I used a part of Junios suggestion
>    Submodules are not to be confused with remotes, which are other
>    repositories of the same project;
>
> I like the "are not to be confused" part, as they warn the reader
> that there will be a paragraph not as concise but touching other
> commands and topics.
>
> Documentation/git-submodule.txt | 50 
> ++++++++++++++++++-----------------------
> 1 file changed, 22 insertions(+), 28 deletions(-)
>
> diff --git a/Documentation/git-submodule.txt 
> b/Documentation/git-submodule.txt
> index 2c25916..d126c86 100644
> --- a/Documentation/git-submodule.txt
> +++ b/Documentation/git-submodule.txt
> @@ -25,22 +25,17 @@ SYNOPSIS
>
> DESCRIPTION
> -----------
> -Submodules allow foreign repositories to be embedded within
> -a dedicated subdirectory of the source tree, always pointed
> -at a particular commit.
> +This command will inspect, update and manage submodules.
>
> -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 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.
> +
> +When cloning or pulling a repository containing submodules however,
> +these will not be checked out by default; the 'init' and 'update'
> +subcommands will maintain submodules checked out and at
> +appropriate revision in your working tree.
>
> Submodules are composed from a so-called `gitlink` tree entry
> in the main repository that refers to a particular commit object
> @@ -51,19 +46,18 @@ 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.
> -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;
> -the 'init' and 'update' subcommands will maintain submodules
> -checked out and at appropriate revision in your working tree.
> -You can briefly inspect the up-to-date status of your submodules
> -using the 'status' subcommand and get a detailed overview of the
> -difference between the index and checkouts using the 'summary'
> -subcommand.
> -
> +Submodules are not to be confused with remotes, which are other
> +repositories 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.
>
> COMMANDS
> --------
> -- 
> 2.4.1.233.g3f9b614.dirty
>
> --