Re: Re* [PATCH] man: git pull -r is a short for --rebase

> "Philip Oakley" <philipoakley@iee.org> writes:
>
>> diff --git a/Documentation/git.txt b/Documentation/git.txt
>> index ca85d1d..75b35ce 100644
>> --- a/Documentation/git.txt
>> +++ b/Documentation/git.txt
>> @@ -22,11 +22,13 @@ unusually rich command set that provides both
>> high-level operations
>>  and full access to internals.
>>
>>  See linkgit:gittutorial[7] to get started, then see
>> -link:everyday.html[Everyday Git] for a useful minimum set of
>> commands, and
>> -"man git-commandname" for documentation of each command.  CVS users
>> may
>> -also want to read linkgit:gitcvs-migration[7].  See
>> -the link:user-manual.html[Git User's Manual] for a more in-depth
>> -introduction.
>> +link:everyday.html[Everyday Git] for a useful minimum set of
>> commands.
>> +Use "man git-commandname" for documentation of each command, or "git
>> help".
>> +
>> +CVS users may also want to read linkgit:gitcvs-migration[7].
>> +
>> +See the link:user-manual.html[Git User's Manual] for a more in-depth
>> +introduction, and linkgit:gitcli[7] for details of git's command
>> line interface.
>>
>>  The '<command>' is either a name of a Git command (see below) or an
>> alias
>>  as defined in the configuration file (see linkgit:git-config[1]).
>
> I would prefer to keep the description section of git(1) not overly
> long.
>
> The first paragraph (not much shown above) concisely describes what
> Git is, so that people who were interested in other "git" can
> quickly tell that this is not a page to read about it.  I think it
> is in good shape.
>
> The purpose of the second paragraph is to guide people who are not
> ready to dive into this page and refer them to other pages with the
> introductory material, and also tell them that they can come back to
> this page to learn the set of commands Git offers once they are
> familiar with the concepts.
>
> And then, before going into the list of commands, we should tell
> them what we are listing, and where they can find more information.
>
> So in that sense, we would really want to keep the second paragraph
> short and to the point.  Referring migrating CVS users to another
> page before they get acquainted with Git like the current page does
> is a mistake.  On the other hand, gitcli may deserve to be mentioned
> in the third paragraph that gives the reader the sense of the overall
> structure of the documentation.

>
> The mention of cvs migration used to be more important in earlier
> days, but I think it was out of place to have it early in the
> document even back then.  It probably can be moved down to the
> FURTHER DOCUMENTATION section.

> -- >8 --
> Subject: [PATCH] Documentation: update the introductory section
>
> The second paragraph in the git(1) description section were meant to
> guide people who are not ready to dive into this page away from here.
> Referring migrating CVS users to another page before they get
> acquainted with Git was somewhat out of place.  Move the reference to
> the "FURTHER DOCUMENTATION" section and push that section down.
>
> Signed-off-by: Junio C Hamano <gitster@pobox.com>
> ---
> Documentation/git.txt | 60
> +++++++++++++++++++++++++++------------------------
> 1 file changed, 32 insertions(+), 28 deletions(-)
>
> diff --git a/Documentation/git.txt b/Documentation/git.txt
> index eb6b2c0..33028a9 100644
> --- a/Documentation/git.txt
> +++ b/Documentation/git.txt
> @@ -22,18 +22,17 @@ unusually rich command set that provides both
> high-level operations
> and full access to internals.
>
> See linkgit:gittutorial[7] to get started, then see
> -link:everyday.html[Everyday Git] for a useful minimum set of
> commands, and
> -"man git-commandname" for documentation of each command.  CVS users
> may
> -also want to read linkgit:gitcvs-migration[7].  See
> -the link:user-manual.html[Git User's Manual] for a more in-depth
> -introduction.
> +link:everyday.html[Everyday Git] for a useful minimum set of
> +commands.  The link:user-manual.html[Git User's Manual] has a more
> +in-depth introduction.
>
> -The '<command>' is either a name of a Git command (see below) or an
> alias
> -as defined in the configuration file (see linkgit:git-config[1]).
> +After you mastered the basic concepts, you can come back to this
> +page to learn what commands git offers.  You can learn more about
> +individual git commands with "git help command".  linkgit:gitcli[7]
> +manual page gives you an overview of the command line command syntax.
>
> -Formatted and hyperlinked version of the latest git
> -documentation can be viewed at
> -`http://git-htmldocs.googlecode.com/git/git.html`.
> +Formatted and hyperlinked version of the latest git documentation
> +can be viewed at `http://git-htmldocs.googlecode.com/git/git.html`.
>
> ifdef::stalenotes[]
> [NOTE]
> @@ -406,24 +405,6 @@ help ...`.
>  linkgit:git-replace[1] for more information.
>
>
> -FURTHER DOCUMENTATION
> ----------------------
> -
> -See the references above to get started using git.  The following is
> -probably more detail than necessary for a first-time user.
> -
> -The link:user-manual.html#git-concepts[git concepts chapter of the
> -user-manual] and linkgit:gitcore-tutorial[7] both provide
> -introductions to the underlying git architecture.
> -
> -See linkgit:gitworkflows[7] for an overview of recommended workflows.
> -
> -See also the link:howto-index.html[howto] documents for some useful
> -examples.
> -
> -The internals are documented in the
> -link:technical/api-index.html[GIT API documentation].
> -
> GIT COMMANDS
> ------------
>
> @@ -843,6 +824,29 @@ The index is also capable of storing multiple
> entries (called "stages")
> for a given pathname.  These stages are used to hold the various
> unmerged version of a file when a merge is in progress.
>
> +FURTHER DOCUMENTATION
> +---------------------
> +
> +See the references in the "description" section to get started
> +using git.  The following is probably more detail than necessary
> +for a first-time user.
> +
> +The link:user-manual.html#git-concepts[git concepts chapter of the
> +user-manual] and linkgit:gitcore-tutorial[7] both provide
> +introductions to the underlying git architecture.
> +
> +See linkgit:gitworkflows[7] for an overview of recommended workflows.
> +
> +See also the link:howto-index.html[howto] documents for some useful
> +examples.
> +
> +The internals are documented in the
> +link:technical/api-index.html[GIT API documentation].
> +
> +Users migrating from CVS may also want to
> +read linkgit:gitcvs-migration[7].
> +
> +
> Authors
> -------
> Git was started by Linus Torvalds, and is currently maintained by
> Junio
> -- 
> 1.7.12.rc3.71.ge297db8
>