patch, 2 partsDocumentation: user-manual: add information about "git help" at the beginning

Talking about "git help" is useful because it has a few more features (like when using it without arguments or with "-a") and it may work on non unix like platforms.

Signed-off-by: Christian Couder <chriscool@tuxfamily.org>
---
 Documentation/user-manual.txt |   18 ++++++++++++++++--
 1 files changed, 16 insertions(+), 2 deletions(-)

	It seems that this patch and the following one have not
	been applyed.

	Here are some more detailed reasons why I think such a patch
	would be useful:

	- neither user-manual.txt nor gitutorial.txt talk, in their
	current state, about "git help",
	- there is a high probability that "man" does not work on
	Windows, though it seems that some work has been done for
	"git help" to work on this platform,
	- "git help" without argument and "git help -a" may be useful
	and have no "man" equivalent, "git help -w" (or "git help -i")
	may also be usefull/friendlier for some people,
	- it seems that "git help" also resolves git aliases,
	- some people still tell that git is not user friendly and
	even develop separate porcelains (like eg) to do a better job
	at helping newbies,
	- at GitTogether'08 many people seemed to agree that "git help"
	should be improved to have more newby friendly features,
	- I don't see the point of trying to improve "git help" any
	further if we don't make it more visible first.

	So, Junio, could you please tell me what is wrong with this patch?

	Thanks in advance,
	Christian.

Christian Couder <chriscool@tuxfamily.org> writes:

First of all, I disagree with your idea to advocate "git help" as _the first way_ to read the manual pages. The way the current user manual is organized is to help command line users, and _the_ way to get to the manual is through the "man" command. Yes, it is very nice of us to provide them _other ways_ to get to them, but that is additional frill. IOW, we _should not_ give impression that you have to use "git" (and "git help") to get to the documentation.

I am not opposed to mentioning "git help" in the early part of the manual, but for the above stated reason, I'd rather swap the above:

	... through the man pages, or linkgit:git-help[1] command.  For
	example, for the command "git clone <repo>", you can either use:

	------------
        $ man git-clone
        ------------

	or:

	------------
        $ git help clone
        ------------

This is a very early part of the user manual, and it would be a good idea to tell the user about the presense of the comprehensive set of manual pages. I also think it is a good idea to tell them that they do not have to use "man" but they can also use "git help", and hint that the "git help" is a separate command (which is already done with the above rewording).

However, this part troubles me heavily in a few ways:

 - "A few more features" may be good in the commit log message for this
   change, but look out of place here.  What additional benefit are the
   readers of the user manual getting here?

   You already told them that a separate "git help" command is available,
   so they can learn how to use it by either "man git-help" or "git help
   help" if they are interested (and I do not think we need a separate
   example for that, after we've shown the use of these two ways for "git
   clone").

 - "self-documenting" is like saying git is self documenting, and/or there
   is a documentation.  Again, I find this an additional noise that does
   not help the readers very much.

It would probably be less objectionable if instead this part said something like:

	With the latter, you can use the manual viewer of your choice; see
	linkgit:git-help[1] for more information.

which would be way more informative than "with a few more features" and "self documenting", I think. Notice that I said "with the _latter_" -- which is consistent to the order I think man/help should be mentioned in the paragraph before this part.