{"thread":{"id":"16353","subject":"[PATCH 1/2 resend] Documentation: user-manual: add information about \"git help\" at the beginning","startedAt":"2008-11-16T17:10:01Z","lastAt":"2008-11-16T18:09:48Z","messageCount":2,"participants":["Christian Couder","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":2},"messages":[{"id":"95953","messageId":"20081116181001.97c45196.chriscool@tuxfamily.org","threadId":"16353","inReplyTo":null,"subject":"[PATCH 1/2 resend] Documentation: user-manual: add information about \"git help\" at the beginning","fromName":"Christian Couder","fromEmail":"chriscool@tuxfamily.org","sentAt":"2008-11-16T17:10:01Z","receivedAt":"2008-11-16T17:10:01Z","isPatch":true,"sender":{"key":"christian.couder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/208954?v=4"},"body":"Talking about \"git help\" is useful because it has a few more\nfeatures (like when using it without arguments or with \"-a\") and\nit may work on non unix like platforms.\n\nSigned-off-by: Christian Couder <chriscool@tuxfamily.org>\n---\n Documentation/user-manual.txt |   18 ++++++++++++++++--\n 1 files changed, 16 insertions(+), 2 deletions(-)\n\n\tIt seems that this patch and the following one have not\n\tbeen applyed.\n\n\tHere are some more detailed reasons why I think such a patch\n\twould be useful:\n\n\t- neither user-manual.txt nor gitutorial.txt talk, in their\n\tcurrent state, about \"git help\",\n\t- there is a high probability that \"man\" does not work on\n\tWindows, though it seems that some work has been done for\n\t\"git help\" to work on this platform,\n\t- \"git help\" without argument and \"git help -a\" may be useful\n\tand have no \"man\" equivalent, \"git help -w\" (or \"git help -i\")\n\tmay also be usefull/friendlier for some people,\n\t- it seems that \"git help\" also resolves git aliases,\n\t- some people still tell that git is not user friendly and\n\teven develop separate porcelains (like eg) to do a better job\n\tat helping newbies,\n\t- at GitTogether'08 many people seemed to agree that \"git help\"\n\tshould be improved to have more newby friendly features,\n\t- I don't see the point of trying to improve \"git help\" any\n\tfurther if we don't make it more visible first.\n\n\tSo, Junio, could you please tell me what is wrong with this patch?\n\n\tThanks in advance,\n\tChristian.\n\ndiff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt\nindex 645d752..48f7189 100644\n--- a/Documentation/user-manual.txt\n+++ b/Documentation/user-manual.txt\n@@ -17,13 +17,27 @@ People needing to do actual development will also want to read\n \n Further chapters cover more specialized topics.\n \n-Comprehensive reference documentation is available through the man\n-pages.  For a command such as \"git clone <repo>\", just use\n+Comprehensive reference documentation is available through either the\n+linkgit:git-help[1] command or the man pages.  For a command such as\n+\"git clone <repo>\", you can use:\n+\n+------------------------------------------------\n+$ git help clone\n+------------------------------------------------\n+\n+or:\n \n ------------------------------------------------\n $ man git-clone\n ------------------------------------------------\n \n+linkgit:git-help[1] has a few more features and is self-documenting\n+using:\n+\n+------------------------------------------------\n+$ git help help\n+------------------------------------------------\n+\n See also <<git-quick-start>> for a brief overview of git commands,\n without any explanation.\n \n-- \n1.6.0.4.617.g39d03\n"},{"id":"95959","messageId":"7vej1b35lf.fsf@gitster.siamese.dyndns.org","threadId":"16353","inReplyTo":"20081116181001.97c45196.chriscool@tuxfamily.org","subject":"Re: [PATCH 1/2 resend] Documentation: user-manual: add information about \"git help\" at the beginning","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2008-11-16T18:09:48Z","receivedAt":"2008-11-16T18:09:48Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Christian Couder <chriscool@tuxfamily.org> writes:\n\n> Talking about \"git help\" is useful because it has a few more\n> features (like when using it without arguments or with \"-a\") and\n> it may work on non unix like platforms.\n\nFirst of all, I disagree with your idea to advocate \"git help\" as _the\nfirst way_ to read the manual pages.  The way the current user manual is\norganized is to help command line users, and _the_ way to get to the\nmanual is through the \"man\" command.  Yes, it is very nice of us to\nprovide them _other ways_ to get to them, but that is additional frill.\nIOW, we _should not_ give impression that you have to use \"git\" (and \"git\nhelp\") to get to the documentation.\n\n> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt\n> index 645d752..48f7189 100644\n> --- a/Documentation/user-manual.txt\n> +++ b/Documentation/user-manual.txt\n> @@ -17,13 +17,27 @@ People needing to do actual development will also want to read\n>  \n>  Further chapters cover more specialized topics.\n>  \n> -Comprehensive reference documentation is available through the man\n> -pages.  For a command such as \"git clone <repo>\", just use\n> +Comprehensive reference documentation is available through either the\n> +linkgit:git-help[1] command or the man pages.  For a command such as\n> +\"git clone <repo>\", you can use:\n> +\n> +------------------------------------------------\n> +$ git help clone\n> +------------------------------------------------\n> +\n> +or:\n>  \n>  ------------------------------------------------\n>  $ man git-clone\n>  ------------------------------------------------\n\nI am not opposed to mentioning \"git help\" in the early part of the manual,\nbut for the above stated reason, I'd rather swap the above:\n\n\t... through the man pages, or linkgit:git-help[1] command.  For\n\texample, for the command \"git clone <repo>\", you can either use:\n\n\t------------\n        $ man git-clone\n        ------------\n\n\tor:\n\n\t------------\n        $ git help clone\n        ------------\n\nThis is a very early part of the user manual, and it would be a good idea\nto tell the user about the presense of the comprehensive set of manual\npages.  I also think it is a good idea to tell them that they do not have\nto use \"man\" but they can also use \"git help\", and hint that the \"git\nhelp\" is a separate command (which is already done with the above\nrewording).\n\nHowever, this part troubles me heavily in a few ways:\n\n> +linkgit:git-help[1] has a few more features and is self-documenting\n> +using:\n\n - \"A few more features\" may be good in the commit log message for this\n   change, but look out of place here.  What additional benefit are the\n   readers of the user manual getting here?\n\n   You already told them that a separate \"git help\" command is available,\n   so they can learn how to use it by either \"man git-help\" or \"git help\n   help\" if they are interested (and I do not think we need a separate\n   example for that, after we've shown the use of these two ways for \"git\n   clone\").\n\n - \"self-documenting\" is like saying git is self documenting, and/or there\n   is a documentation.  Again, I find this an additional noise that does\n   not help the readers very much.\n\nIt would probably be less objectionable if instead this part said\nsomething like:\n\n\tWith the latter, you can use the manual viewer of your choice; see\n\tlinkgit:git-help[1] for more information.\n\nwhich would be way more informative than \"with a few more features\" and\n\"self documenting\", I think.  Notice that I said \"with the _latter_\" --\nwhich is consistent to the order I think man/help should be mentioned in\nthe paragraph before this part.\n"}]}