{"thread":{"id":"33778","subject":"Outdated and broken online versions of user-manual.html","startedAt":"2013-05-10T19:02:30Z","lastAt":"2013-05-20T07:24:39Z","messageCount":4,"participants":["W. Trevor King","Thomas Ackermann","Philip Oakley","Jonathan Nieder"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"216934","messageId":"20130510190229.GA31708@odin.tremily.us","threadId":"33778","inReplyTo":null,"subject":"Outdated and broken online versions of user-manual.html","fromName":"W. Trevor King","fromEmail":"wking@tremily.us","sentAt":"2013-05-10T19:02:30Z","receivedAt":"2013-05-10T19:02:30Z","isPatch":false,"sender":{"key":"wking@tremily.us","avatar":"https://avatars.githubusercontent.com/u/209920?v=4"},"body":"I went to reference some `rebase -i` discussion that landed in 3ca26e8\n(Merge branch 'wk/user-manual', 2013-02-25), and I couldn't find a\nversion of the manual online that contained the new content. There's\na version on kernel.org [1], but that doesn't seem to have been\nupdated since February. There's also a version on git-scm.com [2],\nbut this cuts out after the first section (before “Exploring Git\nhistory”). I'm not sure who's in charge of maintaining either\nlocation, or which (if either) is considered “canonical”.\n\nI'm also surprised that I couldn't find a more obvious link to the\nmanual from git-scm.com (I ended up taking a “See Also” link from\ngittutorial(7) [3]). I'm not sure if this is intentional or not,\nsince git-scm.com does prominently link Pro Git, and that overlaps\nfairly significantly with the manual.\n\nFolks with Git installed will generally have man pages, so it's not a\nbig deal, but having current docs somewhere online to link against\nwould be nice. I'm also curious if I should be linking against a\nparticular location.\n\nCheers,\nTrevor\n\n[1]: https://www.kernel.org/pub/software/scm/git/docs/user-manual.html\n[2]: http://git-scm.com/docs/user-manual.html\n[3]: http://git-scm.com/docs/gittutorial\n\n-- \nThis email may be signed or encrypted with GnuPG (http://www.gnupg.org).\nFor more information, see http://en.wikipedia.org/wiki/Pretty_Good_Privacy\n"},{"id":"216970","messageId":"loom.20130511T092853-808@post.gmane.org","threadId":"33778","inReplyTo":"20130510190229.GA31708@odin.tremily.us","subject":"Re: Outdated and broken online versions of user-manual.html","fromName":"Thomas Ackermann","fromEmail":"th.acker@arcor.de","sentAt":"2013-05-11T07:48:10Z","receivedAt":"2013-05-11T07:48:10Z","isPatch":false,"sender":{"key":"th.acker@arcor.de","avatar":"https://avatars.githubusercontent.com/u/1358536?v=4"},"body":"W. Trevor King tremily.us> writes:\n\n> \n> I'm also surprised that I couldn't find a more obvious link to the\n> manual from git-scm.com (I ended up taking a “See Also” link from\n> gittutorial(7) [3]). I'm not sure if this is intentional or not,\n> since git-scm.com does prominently link Pro Git, and that overlaps\n> fairly significantly with the manual.\n> \n> Folks with Git installed will generally have man pages, so it's not a\n> big deal, but having current docs somewhere online to link against\n> would be nice. I'm also curious if I should be linking against a\n> particular location.\n> \n\nIMHO user-manual is a natural step for a Git beginner after reading one \nof the books like \"Pro Git\" and before he is ready to digest the man pages. \nBut up to now there are several problems with user-manual besides the\nproblems described by Trevor:\n(1) Very poor html formatting (document type \"book\" causes\nugly TOCs per section and there's a \"Part I\" without a \"Part II\")\n(2) Partly outdated content\n(3) Sub-optimal structuring (to-do list as part of the document,\nglossary not at the end of the document)\n(4) User-manual.PDF uses an independent tool chain which makes it\nharder to do improvements for user-manual.html and also is the only\npdf doc we are creating. IMHO we should remove this altogether.\n(5) Large overlapping with the tutorials. IMHO all of the \ntutorials should be blended into user-manual\n\nI am currently working on (1)-(4) and then aiming for (5).\nComments are welcome ...\n\n---\nThomas\n"},{"id":"216989","messageId":"BE32A698F2774BD5B5235264B13A46C8@PhilipOakley","threadId":"33778","inReplyTo":"loom.20130511T092853-808@post.gmane.org","subject":"Re: Outdated and broken online versions of user-manual.html","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2013-05-11T11:36:21Z","receivedAt":"2013-05-11T11:36:21Z","isPatch":false,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Thomas Ackermann\" \nSent: Saturday, May 11, 2013 8:48 AM\n> W. Trevor King tremily.us> writes:\n>\n>>\n>> I'm also surprised that I couldn't find a more obvious link to the\n>> manual from git-scm.com (I ended up taking a “See Also” link from\n>> gittutorial(7) [3]). I'm not sure if this is intentional or not,\n>> since git-scm.com does prominently link Pro Git, and that overlaps\n>> fairly significantly with the manual.\n>>\n>> Folks with Git installed will generally have man pages, so it's not a\n>> big deal, but having current docs somewhere online to link against\n>> would be nice. I'm also curious if I should be linking against a\n>> particular location.\n>>\n>\n> IMHO user-manual is a natural step for a Git beginner after reading \n> one\n> of the books like \"Pro Git\" and before he is ready to digest the man \n> pages.\n> But up to now there are several problems with user-manual besides the\n> problems described by Trevor:\n> (1) Very poor html formatting (document type \"book\" causes\n> ugly TOCs per section and there's a \"Part I\" without a \"Part II\")\n> (2) Partly outdated content\n> (3) Sub-optimal structuring (to-do list as part of the document,\n> glossary not at the end of the document)\n> (4) User-manual.PDF uses an independent tool chain which makes it\n> harder to do improvements for user-manual.html and also is the only\n> pdf doc we are creating. IMHO we should remove this altogether.\n> (5) Large overlapping with the tutorials. IMHO all of the\n> tutorials should be blended into user-manual\n>\n> I am currently working on (1)-(4) and then aiming for (5).\n> Comments are welcome ...\n>\n> ---\n> Thomas\n\nI too had noticed that both the User-Manual and git Everyday are not \nformatted in a manner that allows them to be accessed via 'git help'.\n\nI recently added a '--guides' option to 'git help' (v1.8.2-377-g73903d0) \nwhich will show the common guides but was frustrated that I couldn't \ninclude either the user-manual or everday in the list.\n\nI'd welcome the provision of a 'man'/'html' formatted version of the two \nguides. Are you expecting to make then compatible with the man format?\n\nI would be a little cautious of your point 5 if it squoze everything \ninto one overlong document at the expense of losing the shorter \ndocuments - one can't eat a whole melon in one bite ;-) That said there \nis a significant opportunity for rationalisation and clarity \nimprovement, even if it is only a proper realisation of where we \ndeliberately duplicate information for ease of user learning.\n\nI also liked the idea of all the documenation being collated into one \nHumongous pdf as a reference (there was a patch a while back - don't \nhave a reference right now).\n\nPhilip \n"},{"id":"217963","messageId":"20130520072439.GF2919@elie.Belkin","threadId":"33778","inReplyTo":"BE32A698F2774BD5B5235264B13A46C8@PhilipOakley","subject":"Re: Outdated and broken online versions of user-manual.html","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2013-05-20T07:24:39Z","receivedAt":"2013-05-20T07:24:39Z","isPatch":false,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Philip Oakley wrote:\n> From: \"Thomas Ackermann\" \n\n>> (5) Large overlapping with the tutorials. IMHO all of the\n>> tutorials should be blended into user-manual\n[...]\n> I would be a little cautious of your point 5 if it squoze everything into\n> one overlong document at the expense of losing the shorter documents - one\n> can't eat a whole melon in one bite ;-)\n\nYes.\n\nOnce there was a lovely file at\n\n\tDocumentation/howto/isolate-bugs-with-bisect.txt\n\nexplaining how to use \"git bisect\" to find which commit caused a\nkernel regression. That it was a small independent file that didn't\nassume the reader had read much before was very helpful, since it\nmeant people could easily point novices to that page and say \"It's\neasy!\" when asking them to track down a bug.\n\nNowadays that content is gracefully included in the user-manual under\nthe heading [[using-bisect]]. But I never point people to it any more;\nI just write out the steps by hand, to avoid intimidating them.\n\nIdeally this content would be in an EXAMPLE or TUTORIAL section of the\ngit-bisect(1) manpage for easier reference.\n\nThanks,\nJonathan\n"}]}